fluentui-svelte 0.4.0 → 0.6.0

package/dist/components/tag-picker/types.d.ts

@@ -0,0 +1,122 @@
+import type { Component, Snippet } from 'svelte';
+import type { HTMLAttributes, HTMLInputAttributes, SVGAttributes } from 'svelte/elements';
+import type { FSContext } from '../../internal/index.js';
+import type { ListViewItemProps } from '../list-view/types.ts';
+import type { TagGroupProps } from '../tag/types.ts';
+export type TagPickerSizes = 'medium' | 'large' | 'extra-large';
+/** @propsmith TagPickerProps */
+export type TagPickerProps = {
+    /** The DOM reference of the wrapper element.
+     * @bindable
+     */
+    ref?: HTMLDivElement;
+    /** The DOM reference of the input element.
+     * @bindable
+     */
+    inputRef?: HTMLInputElement;
+    /** The values of the chosen options, shown as tags in the control. A value no option has is shown as it is.
+     * @default []
+     * @bindable
+     */
+    selectedOptions?: string[];
+    /** The text typed in the input. It filters the options, and is cleared when one is chosen.
+     * @default ''
+     * @bindable
+     */
+    value?: string;
+    /** Controls the open state of the option list.
+     * @default false
+     * @bindable
+     */
+    open?: boolean;
+    /** Limits the picker to one tag: choosing an option replaces the current one and closes the list. */
+    single?: boolean;
+    /** Disables the user interaction: the input, the tags and the list. */
+    disabled?: boolean;
+    /** The size of the control. It also picks the size of the tags.
+     * @default 'medium'
+     */
+    size?: TagPickerSizes;
+    /** The placeholder text of the input. */
+    placeholder?: string;
+    /** The message shown in place of the list when there is no option left to choose.
+     * @default 'No options available'
+     */
+    notFoundText?: string;
+    /** The dropdown arrow. Pass `null` to remove it.
+     * @default ChevronDownRegular
+     * @type Snippet | Component | null
+     */
+    expandIcon?: Snippet<[SVGAttributes<SVGElement>]> | Component<SVGAttributes<SVGElement>> | null;
+    /** A button-like element rendered at the end of the control, before the dropdown arrow. */
+    secondaryAction?: Snippet;
+    /** Renders the tag of a chosen option, to give it media or custom text. Falls back to a plain tag.
+     * Render a `Tag` with the given `value`, and `role="listitem"`.
+     * @type Snippet<[{ value: string; text: string }]>
+     */
+    tag?: Snippet<[{
+        value: string;
+        text: string;
+    }]>;
+    /** The props to spread on the group holding the tags. This is where its `aria-label` goes.
+     * @type TagGroupProps
+     */
+    tagGroupProps?: Omit<TagGroupProps, 'children' | 'size' | 'appearance' | 'disabled' | 'dismissible' | 'selectedValues' | 'onTagSelect' | 'onDismiss'>;
+    /** The props to spread on the input. This is where its accessible name (`aria-label`) and
+     * `readonly` (to turn the input into a plain trigger) go.
+     * @type HTMLInputAttributes
+     */
+    inputProps?: Omit<HTMLInputAttributes, 'value' | 'type' | 'role' | 'disabled' | 'oninput' | 'onkeydown'>;
+    /** Called when an option is chosen, or a tag is removed. */
+    onSelectionChange?: (e: Event, selectedOptions: string[]) => void;
+    /** Called when Enter is pressed with text in the input and no option under the cursor. This is
+     * where a free-form tag is added.
+     */
+    querySubmitted?: (e: KeyboardEvent, query: string) => void;
+    /** The options. Leave it out to get a picker without a list. */
+    children?: Snippet;
+} & Omit<HTMLAttributes<HTMLDivElement>, 'children'>;
+export type OptionType = {
+    id: string;
+    value: string;
+    disabled?: boolean;
+};
+export type TagPickerContext = FSContext<null, {
+    readonly query: string;
+    readonly selectedOptions: string[];
+    readonly open: boolean;
+}, null, {
+    /** Remembers what the tag of `value` says. Every option calls it, on screen or not. */
+    setLabel: (value: string, text: string) => void;
+    setOption: (option: OptionType) => void;
+    deleteOption: (id: string) => void;
+    chooseOption: (e: Event, id: string) => void;
+}>;
+/** @propsmith TagPickerOptionProps */
+export type TagPickerOptionProps = {
+    /** The value added to `selectedOptions` when the option is chosen. */
+    value: string;
+    /** The text the option is filtered by, and the text of its tag. Falls back to `value`. */
+    text?: string;
+    /** The id of the option element, referenced by the input through `aria-activedescendant`.
+     * Falls back to a generated id.
+     */
+    id?: string;
+    /** The DOM reference of the option element.
+     * @bindable
+     */
+    ref?: HTMLLIElement;
+    /** Takes the option out of reach: it is shown, but the cursor steps over it. */
+    disabled?: boolean;
+} & Omit<ListViewItemProps<'li'>, 'as' | 'value' | 'onAction' | 'checkmark'>;
+/** @propsmith TagPickerOptionGroupProps */
+export type TagPickerOptionGroupProps = {
+    /** The label of the group. */
+    label: string;
+    /** The DOM reference of the group element.
+     * @bindable
+     */
+    ref?: HTMLUListElement;
+    /** The options of the group. */
+    children?: Snippet;
+} & Omit<HTMLAttributes<HTMLUListElement>, 'children'>;

package/dist/components/tag-picker/types.js

@@ -0,0 +1 @@
+export {};

package/dist/components/tree-view/docs/llms.md

@@ -35,7 +35,7 @@ Nesting a TreeView inside a TreeViewItem of type='branch' creates a subtree. Use
 
 ### Checkable Items
 
-Set `selectionMode="multiple"` to render checkboxes on selectable items.
+Set `selectionMode` to `"multiple" | "single"` to render checkboxes on selectable items.
 
 ```svelte
 <TreeView selectionMode="multiple">
@@ -50,6 +50,132 @@ Set `selectionMode="multiple"` to render checkboxes on selectable items.
 </TreeView>
 ```
 
+### Single selection
+
+Set `selectionMode` to `single` so checking an item unchecks the previous one, and branches no longer cascade to their children.
+
+```svelte
+<script>
+	let checked = $state([]);
+</script>
+
+<TreeView selectionMode="single" bind:checkedItems={checked}>
+	<TreeViewItem id="fruits" type="branch" open>
+		<TreeViewItemContent>Fruits</TreeViewItemContent>
+		<TreeView>
+			<TreeViewItem id="apple">
+				<TreeViewItemContent>Apple</TreeViewItemContent>
+			</TreeViewItem>
+			<TreeViewItem id="banana">
+				<TreeViewItemContent>Banana</TreeViewItemContent>
+			</TreeViewItem>
+		</TreeView>
+	</TreeViewItem>
+	<TreeViewItem id="vegetables">
+		<TreeViewItemContent>Vegetables</TreeViewItemContent>
+	</TreeViewItem>
+</TreeView>
+
+<p>Checked: {checked.join(', ')}</p>
+```
+
+### Icons
+
+Use `iconBefore` and `iconAfter` to render icons around the label. Every item reserves the space of the expand chevron, so checkboxes and icons stay aligned between branches and leaves.
+
+```svelte
+<script>
+	import { TreeView, TreeViewItem, TreeViewItemContent } from 'fluentui-svelte';
+	import FolderRegular from 'fluentui-icons-svelte/FolderRegular.svelte';
+	import DocumentRegular from 'fluentui-icons-svelte/DocumentRegular.svelte';
+	import ImageRegular from 'fluentui-icons-svelte/ImageRegular.svelte';
+	import StarRegular from 'fluentui-icons-svelte/StarRegular.svelte';
+	import LockClosedRegular from 'fluentui-icons-svelte/LockClosedRegular.svelte';
+</script>
+
+{#snippet folder()}<FolderRegular width="1.25rem" />{/snippet}
+{#snippet document()}<DocumentRegular width="1.25rem" />{/snippet}
+{#snippet image()}<ImageRegular width="1.25rem" />{/snippet}
+{#snippet star()}<StarRegular width="1rem" />{/snippet}
+{#snippet lock()}<LockClosedRegular width="1rem" />{/snippet}
+
+<TreeView selectionMode="multiple">
+	<TreeViewItem id="documents" type="branch" open>
+		<TreeViewItemContent iconBefore={folder}>Documents</TreeViewItemContent>
+		<TreeView>
+			<TreeViewItem id="report">
+				<TreeViewItemContent iconBefore={document} iconAfter={star}>Report</TreeViewItemContent>
+			</TreeViewItem>
+			<TreeViewItem id="photo">
+				<TreeViewItemContent iconBefore={image}>Photo</TreeViewItemContent>
+			</TreeViewItem>
+		</TreeView>
+	</TreeViewItem>
+	<TreeViewItem id="notes">
+		<TreeViewItemContent iconBefore={document} iconAfter={lock}>Notes</TreeViewItemContent>
+	</TreeViewItem>
+</TreeView>
+```
+
+### Aside and actions
+
+`aside` is pinned to the end of the row. `actions` comes after it and is revealed when the row is hovered or focused.
+
+```svelte
+<script>
+	import { TreeView, TreeViewItem, TreeViewItemContent, Button } from 'fluentui-svelte';
+	import DocumentRegular from 'fluentui-icons-svelte/DocumentRegular.svelte';
+	import MoreHorizontalRegular from 'fluentui-icons-svelte/MoreHorizontalRegular.svelte';
+</script>
+
+{#snippet document()}<DocumentRegular width="1.25rem" />{/snippet}
+{#snippet fileSize()}<span>2 KB</span>{/snippet}
+{#snippet more()}
+	<Button appearance="subtle" onclick={(e) => e.stopPropagation()} aria-label="More actions"
+		><MoreHorizontalRegular width="1rem" /></Button
+	>
+{/snippet}
+
+<TreeView>
+	<TreeViewItem id="report">
+		<TreeViewItemContent iconBefore={document} aside={fileSize} actions={more}>Report</TreeViewItemContent>
+	</TreeViewItem>
+	<TreeViewItem id="annual-summary">
+		<TreeViewItemContent iconBefore={document} aside={fileSize} actions={more}>Annual summary</TreeViewItemContent>
+	</TreeViewItem>
+</TreeView>
+```
+
+### Sizes
+
+Set `size` to `small`, `medium` or `large` on the root `TreeView`.
+
+```svelte
+<TreeView size="small">...</TreeView>
+<TreeView size="medium">...</TreeView>
+<TreeView size="large">...</TreeView>
+```
+
+### Disabled items
+
+A disabled item can't be opened or checked, and it is skipped when its parent checks its children, which leaves the parent in its mixed state.
+
+```svelte
+<TreeView selectionMode="multiple">
+	<TreeViewItem id="fruits" type="branch" open>
+		<TreeViewItemContent>Fruits</TreeViewItemContent>
+		<TreeView>
+			<TreeViewItem id="apple">
+				<TreeViewItemContent>Apple</TreeViewItemContent>
+			</TreeViewItem>
+			<TreeViewItem id="banana" disabled>
+				<TreeViewItemContent>Banana</TreeViewItemContent>
+			</TreeViewItem>
+		</TreeView>
+	</TreeViewItem>
+</TreeView>
+```
+
 ### Controlling Open and Checked State
 
 Use the bindable `openItems` and `checkedItems` props on the root `TreeView` to control state programmatically.
@@ -70,6 +196,45 @@ Use the bindable `openItems` and `checkedItems` props on the root `TreeView` to
 		</TreeView>
 	</TreeViewItem>
 </TreeView>
+
+<p>Open: {openItems.join(', ')}</p>
+<p>Checked: {checkedItems.join(', ')}</p>
+```
+
+### Events
+
+`onCheckedChange` and `onOpenChange` on the TreeView receive the resulting ids. The same props on a TreeViewItem receive the item and its new state, including the children a branch cascades to.
+
+```svelte
+<script>
+	let treeEvent = $state('');
+	let itemEvent = $state('');
+</script>
+
+<TreeView
+	selectionMode="multiple"
+	onCheckedChange={(e, checkedItems) => (treeEvent = 'Checked: ' + checkedItems.join(', '))}
+	onOpenChange={(e, openItems) => (treeEvent = 'Open: ' + openItems.join(', '))}
+>
+	<TreeViewItem
+		id="fruits"
+		type="branch"
+		onOpenChange={(e, { id, open }) => (itemEvent = id + (open ? ' opened' : ' closed'))}
+	>
+		<TreeViewItemContent>Fruits</TreeViewItemContent>
+		<TreeView>
+			<TreeViewItem
+				id="apple"
+				onCheckedChange={(e, { id, checked }) => (itemEvent = id + (checked ? ' checked' : ' unchecked'))}
+			>
+				<TreeViewItemContent>Apple</TreeViewItemContent>
+			</TreeViewItem>
+		</TreeView>
+	</TreeViewItem>
+</TreeView>
+
+<p>Tree: {treeEvent}</p>
+<p>Item: {itemEvent}</p>
 ```
 
 ## Component Props (TreeView)

package/dist/components/tree-view/tree-view-item-content.svelte

@@ -47,10 +47,8 @@
 		wrapperAttributes={{
 			onclick: (e) => {
 				e.stopPropagation();
-				if (ITEM_CONTEXT.disabled) {
-					e.preventDefault();
-					return;
-				}
+				e.preventDefault();
+				if (ITEM_CONTEXT.disabled) return;
 				handleCheck(e, ITEM_CONTEXT.id, !ITEM_CONTEXT.checked);
 			}
 		}}
@@ -87,9 +85,12 @@
 
 <style>
 	.fs-tree-view-item-content {
+		--chevron-width: 1.2rem;
+		--gap: 0.75rem;
+		box-sizing: border-box;
 		display: flex;
 		align-items: center;
-		gap: 0.75rem;
+		gap: var(--gap);
 		position: relative;
 		border-radius: var(--fs-control-border-radius);
 		font-size: var(--fs-body-font-size);
@@ -100,20 +101,26 @@
 		width: 100%;
 		text-align: left;
 		user-select: none;
+		&:not(:has(:global(.branch-indicator))) {
+			--leaf-offset: calc(var(--chevron-width) + var(--gap) + 0rem);
+		}
 		&.size-small {
 			font-size: var(--fs-body2-font-size);
 			padding: 0.125rem 0.5rem;
-			padding-left: calc(0.5rem + 1.5rem * var(--depth, 0));
+			padding-left: calc(0.5rem + 2rem * var(--depth, 0) + var(--leaf-offset, 0rem));
+			min-height: 1.75rem;
 		}
 		&.size-medium {
 			font-size: var(--fs-body-font-size);
 			padding: 0.25rem 0.625rem;
-			padding-left: calc(0.625rem + 1.5rem * var(--depth, 0));
+			padding-left: calc(0.625rem + 2rem * var(--depth, 0) + var(--leaf-offset, 0rem));
+			min-height: 2rem;
 		}
 		&.size-large {
 			font-size: var(--fs-subtitle2-font-size);
 			padding: 0.375rem 0.75rem;
-			padding-left: calc(0.75rem + 1.5rem * var(--depth, 0));
+			padding-left: calc(0.75rem + 2rem * var(--depth, 0) + var(--leaf-offset, 0rem));
+			min-height: 2.25rem;
 		}
 
 		&::after {
@@ -155,4 +162,30 @@
 			fill: currentColor;
 		}
 	}
+	.fs-tree-view-item-icon-before,
+	.fs-tree-view-item-icon-after,
+	.fs-tree-view-item-aside,
+	.fs-tree-view-item-actions {
+		display: inline-flex;
+		align-items: center;
+		flex-shrink: 0;
+	}
+	.fs-tree-view-item-aside,
+	.fs-tree-view-item-actions {
+		margin-left: auto;
+	}
+	.fs-tree-view-item-aside + .fs-tree-view-item-actions {
+		margin-left: 0;
+	}
+	.fs-tree-view-item-actions {
+		opacity: 0;
+		@media (hover: none) {
+			opacity: 1;
+		}
+	}
+	.fs-tree-view-item-content:hover .fs-tree-view-item-actions,
+	.fs-tree-view-item-content:focus-within .fs-tree-view-item-actions,
+	:global(.fs-tree-view-item:focus-visible) > .fs-tree-view-item-content .fs-tree-view-item-actions {
+		opacity: 1;
+	}
 </style>

package/dist/components/tree-view/tree-view-item.svelte

@@ -32,6 +32,8 @@
 		type = 'item',
 		open = (openItems instanceof Set ? openItems.has(id) : openItems.includes(id)) || undefined,
 		checked = (checkedItems instanceof Set ? checkedItems.has(id) : checkedItems.includes(id)) || undefined,
+		onCheckedChange,
+		onOpenChange,
 		children,
 		...attributes
 	}: TreeViewItemProps = $props();
@@ -61,6 +63,12 @@
 		get parentId() {
 			return itemContext?.id;
 		},
+		get onCheckedChange() {
+			return onCheckedChange;
+		},
+		get onOpenChange() {
+			return onOpenChange;
+		},
 		get open() {
 			return open;
 		},
@@ -190,7 +198,8 @@
 			outline: 2px solid var(--fs-focus-stroke-outer);
 			outline-offset: 2px;
 		}
-		&.open :global(.branch-indicator) {
+		/* Only the chevron of this item's own row, not the ones of the branches nested inside it. */
+		&.open > :global(.fs-tree-view-item-content .branch-indicator) {
 			rotate: 90deg;
 		}
 	}

package/dist/components/tree-view/tree-view.svelte

@@ -89,12 +89,21 @@
 					await tick();
 				}
 
+				const wasChecked = new Map(state.TREE_NODES.entries().map(([nodeId, node]) => [nodeId, !!node.checked]));
+
 				if (selectionMode === 'single') {
 					traversalSyncSingleSelection(id, state.TREE_NODES, checkedItems);
-					return;
+				} else {
+					traversalSync(id, state.TREE_NODES, checkedItems, checked);
 				}
 
-				traversalSync(id, state.TREE_NODES, checkedItems, checked);
+				// Every item the click reached reports its own change, the tree reports the resulting set.
+				for (const node of state.TREE_NODES.values()) {
+					if (!!node.checked !== wasChecked.get(node.id)) {
+						node.onCheckedChange?.(e as Event, { id: node.id, checked: !!node.checked });
+					}
+				}
+				treeViewContext.events.onCheckedChange(e as Event, Array.from(checkedItems));
 			},
 			openItem: (e, id) => {
 				if (openItems instanceof SvelteSet) {
@@ -105,6 +114,9 @@
 				const node = treeViewContext.state.TREE_NODES.get(id)!;
 
 				node.open = true;
+
+				node.onOpenChange?.(e as Event, { id, open: true });
+				treeViewContext.events.onOpenChange(e as Event, Array.from(openItems));
 			},
 			closeItem: (e, id) => {
 				const { state } = treeViewContext;
@@ -122,6 +134,9 @@
 				if (virtualizer && state.forceVirtualRender) {
 					state.forceVirtualRender = false;
 				}
+
+				node.onOpenChange?.(e as Event, { id, open: false });
+				treeViewContext.events.onOpenChange(e as Event, Array.from(openItems));
 			},
 			registerItem: (node) => {
 				treeViewContext.state.TREE_NODES.set(node.id, node);

package/dist/components/tree-view/tree-view.svelte.js

@@ -102,10 +102,12 @@ export function traversalSyncSingleSelection(itemId, state, iterable) {
     node.indeterminate = false;
     if (iterable instanceof Set) {
         iterable.clear();
-        iterable.add(node.id);
+        if (node.checked)
+            iterable.add(node.id);
     }
     else if (Array.isArray(iterable)) {
         iterable.length = 0;
-        iterable.push(node.id);
+        if (node.checked)
+            iterable.push(node.id);
     }
 }

package/dist/components/tree-view/types.d.ts

@@ -14,6 +14,8 @@ export type TreeViewNode = {
     checked?: boolean;
     indeterminate?: boolean;
     open?: boolean;
+    onCheckedChange?: TreeViewItemProps['onCheckedChange'];
+    onOpenChange?: TreeViewItemProps['onOpenChange'];
 };
 export type TreeViewEvent<T extends Record<string, unknown> | Iterable<unknown>> = (e: Event, data: T) => void;
 /**
@@ -179,6 +181,8 @@ export type TreeViewItemContext = {
     readonly id: string;
     readonly type: TreeViewItemType;
     readonly parentId?: string;
+    readonly onCheckedChange?: TreeViewItemProps['onCheckedChange'];
+    readonly onOpenChange?: TreeViewItemProps['onOpenChange'];
     open?: boolean;
     checked?: boolean;
     indeterminate?: boolean;

package/dist/index.d.ts

@@ -57,6 +57,8 @@ export { default as Persona } from './components/persona/persona.svelte';
 export { default as ProgressBar } from './components/progress-bar/progress-bar.svelte';
 export { default as ProgressRing } from './components/progress-ring/progress-ring.svelte';
 export { default as RadioButton } from './components/radio-button/radio-button.svelte';
+export { default as Rating } from './components/rating/rating.svelte';
+export type { RatingProps } from './components/rating/types.js';
 export { default as Skeleton } from './components/skeleton/skeleton.svelte';
 export { default as Slider } from './components/slider/slider.svelte';
 export { default as Table } from './components/table/table.svelte';
@@ -70,6 +72,11 @@ export { default as TableCellLayout } from './components/table/table-cell-layout
 export { default as TableCellActions } from './components/table/table-cell-actions.svelte';
 export { default as TabView } from './components/tab-view/tab-view.svelte';
 export { default as TabViewTab } from './components/tab-view/tab-view-tab.svelte';
+export { default as Tag } from './components/tag/tag.svelte';
+export { default as TagGroup } from './components/tag/tag-group.svelte';
+export { default as TagPicker } from './components/tag-picker/tag-picker.svelte';
+export { default as TagPickerOption } from './components/tag-picker/option.svelte';
+export { default as TagPickerOptionGroup } from './components/tag-picker/option-group.svelte';
 export { default as TextArea } from './components/textarea/textarea.svelte';
 export { default as TextBox } from './components/text-box/text-box.svelte';
 export { default as TextBoxButton } from './components/text-box/text-box-button.svelte';

package/dist/index.js

@@ -109,6 +109,9 @@ export { default as ProgressRing } from './components/progress-ring/progress-rin
 // Start RadioButton Component
 export { default as RadioButton } from './components/radio-button/radio-button.svelte';
 // End RadioButton Component
+// Start Rating Component
+export { default as Rating } from './components/rating/rating.svelte';
+// End Rating Component
 // Start Skeleton Component
 export { default as Skeleton } from './components/skeleton/skeleton.svelte';
 // End Skeleton Component
@@ -130,6 +133,15 @@ export { default as TableCellActions } from './components/table/table-cell-actio
 export { default as TabView } from './components/tab-view/tab-view.svelte';
 export { default as TabViewTab } from './components/tab-view/tab-view-tab.svelte';
 // End TabView Component
+// Start Tag Component
+export { default as Tag } from './components/tag/tag.svelte';
+export { default as TagGroup } from './components/tag/tag-group.svelte';
+// End Tag Component
+// Start TagPicker Component
+export { default as TagPicker } from './components/tag-picker/tag-picker.svelte';
+export { default as TagPickerOption } from './components/tag-picker/option.svelte';
+export { default as TagPickerOptionGroup } from './components/tag-picker/option-group.svelte';
+// End TagPicker Component
 // Start TextArea Component
 export { default as TextArea } from './components/textarea/textarea.svelte';
 // End TextArea Component

package/dist/internal/constants.d.ts

@@ -20,7 +20,3 @@ export declare const DIRECTION: {
 export declare const PREFIX = "fs";
 export declare const DEFAULT_OFFSET = 8;
 export declare const VIRTUAL_ELEMENT: VirtualElement;
-export declare const fake: {
-    id: string;
-    name: string;
-}[];