fluentui-svelte 0.5.0 → 0.7.0

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

@@ -0,0 +1,111 @@
+# Rating
+
+A rating lets users give a value to an item by selecting one of a row of stars. It supports half-filled stars, four sizes and a custom number of items.
+
+## Usage
+
+```svelte
+<script>
+	import { Rating } from 'fluentui-svelte';
+
+	let value = $state(3);
+</script>
+
+<Rating bind:value />
+```
+
+## Component API
+
+A rating lets users give a value to an item, using a row of symbols such as stars. It supports half-filled items and four sizes.
+
+## Examples
+
+### Bind the value
+
+Use `bind:value` to read the rating the user picks.
+
+```svelte
+<script>
+	let value = $state(3);
+</script>
+
+<Rating bind:value />
+```
+
+### Half stars
+
+Set `step={0.5}` to let users pick half-filled stars.
+
+```svelte
+<Rating value={2.5} step={0.5} />
+```
+
+### Quarter stars
+
+Until the user rates, a fractional `value` is drawn in quarters, which is handy to show an average. Once the user picks a star, the rating snaps to the `step`.
+
+```svelte
+<Rating value={3.75} />
+```
+
+### Size
+
+Use `size` to choose between `small`, `medium`, `large` and `extra-large`.
+
+```svelte
+<Rating value={3} size="small" />
+<Rating value={3} size="medium" />
+<Rating value={3} size="large" />
+<Rating value={3} size="extra-large" />
+```
+
+### Shape
+
+Use `iconFilled` and `iconOutline` to replace the stars with any other icon component. Both fall back to the star when omitted, and partially filled items are clipped, so custom shapes also work with `step={0.5}`.
+
+```svelte
+<script>
+	import { HeartFilled, HeartRegular } from 'fluentui-icons-svelte';
+</script>
+
+<Rating value={3} iconFilled={HeartFilled} iconOutline={HeartRegular} />
+```
+
+### Max
+
+Use `max` to change the number of stars.
+
+```svelte
+<Rating value={4} max={10} />
+```
+
+### Item label
+
+Use `itemLabel` to customize the accessible label of each radio input.
+
+```svelte
+<Rating value={3} itemLabel={(rating) => `${rating} out of 5 stars`} />
+```
+
+The root is the control element. HTML attributes, class and ref apply to that element. There is no separate wrapper API.
+
+## Component Props
+
+<!-- DO NOT EDIT THIS SECTION (propsmith generated) -->
+<!-- props:RatingProps -->
+
+| Name                                                                                                                               | Type                                                                | Default                       | Description                                                                                                                                 |
+| ---------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| `value` _bindable_                                                                                                                 | `number`                                                            | `0`                           | The current rating. Fractions are drawn in quarters until the user rates.                                                                   |
+| `max`                                                                                                                              | `number`                                                            | `5`                           | The number of items displayed. Must be a whole number greater than 1.                                                                       |
+| `step`                                                                                                                             | `1` &#124; `0.5`                                                    | `1`                           | The precision of the rating. `0.5` allows half-filled items.                                                                                |
+| `size`                                                                                                                             | `'small'` &#124; `'medium'` &#124; `'large'` &#124; `'extra-large'` | `'extra-large'`               | The size of the rating items.                                                                                                               |
+| `iconFilled`                                                                                                                       | `Component`                                                         |                               | The icon of a filled item. Falls back to a filled star. Partially filled items are clipped, so it also works with half steps.               |
+| `iconOutline`                                                                                                                      | `Component`                                                         |                               | The icon of an empty item. Falls back to an outlined star.                                                                                  |
+| `itemLabel`                                                                                                                        | `(rating: number) => string`                                        | `` (rating) => `${rating}` `` | Generates the accessible label of the radio input for a rating value.                                                                       |
+| `onChange`                                                                                                                         | `(value: number) => void`                                           |                               | Called when the user changes the rating.                                                                                                    |
+| `wrapperRef` _bindable_                                                                                                            | `HTMLDivElement` &#124; `null`                                      |                               | The DOM reference of the radiogroup element.                                                                                                |
+| `wrapperAttributes`                                                                                                                | `HTMLAttributes`                                                    |                               | The attributes to spread on the radiogroup element. This is where its `aria-label`, `aria-labelledby`, `aria-invalid`, `id` and `class` go. |
+| `HTMLInputAttributes` without `type`, `value`, `checked`, `max`, `step`, `size`, `style`, `aria-label`, `aria-invalid`, `children` |                                                                     |                               |                                                                                                                                             |
+
+<!-- /props:RatingProps -->

package/dist/components/rating/rating.svelte

@@ -0,0 +1,247 @@
+<script lang="ts">
+	import { claimLabel } from '../label/label-context.js';
+	import { invokeHandlers } from '../../internal/index.js';
+	import { PREFIX } from '../../internal/constants.js';
+	import StarFilled from 'fluentui-icons-svelte/StarFilled.svelte';
+	import StarHalfRegular from 'fluentui-icons-svelte/StarHalfRegular.svelte';
+	import StarOneQuarterRegular from 'fluentui-icons-svelte/StarOneQuarterRegular.svelte';
+	import StarRegular from 'fluentui-icons-svelte/StarRegular.svelte';
+	import StarThreeQuarterRegular from 'fluentui-icons-svelte/StarThreeQuarterRegular.svelte';
+	import type { RatingProps } from './types.js';
+
+	const FALLBACK_ID = $props.id();
+	const COMPONENT_NAME = 'rating';
+	const ID = `${PREFIX}${COMPONENT_NAME}-${FALLBACK_ID}`;
+	const VALUE_ID = `${ID}-value`;
+
+	const labelContext = claimLabel(() => undefined);
+
+	let {
+		value = $bindable(0),
+		max = 5,
+		step = 1,
+		size = 'extra-large',
+		iconFilled,
+		iconOutline,
+		id = ID,
+		class: classes,
+		name = id,
+		itemLabel = (rating) => `${rating}`,
+		onChange,
+		wrapperRef = $bindable(null),
+		wrapperAttributes,
+		onclick,
+		onpointerenter,
+		...attributes
+	}: RatingProps = $props();
+
+	/** Until the user rates, the value is only displayed, so it is drawn with the precision of a quarter. */
+	let rated = $state(false);
+	let hovered = $state<number>();
+
+	const _max = $derived.by(() => {
+		if (!Number.isInteger(max) || max <= 1) throw new Error('Max must be a whole number greater than 1');
+		return max;
+	});
+	const items = $derived(Array.from({ length: _max }, (_, index) => index + 1));
+	const shown = $derived(hovered ?? value);
+	const checkedValue = $derived(value === 0 ? 0 : Math.min(_max, Math.max(step, Math.round(value / step) * step)));
+
+	const custom = $derived(!!(iconFilled || iconOutline));
+
+	/** How much of the item is filled, snapped to the precision it is shown with. */
+	function fillFor(item: number) {
+		const fill = Math.min(Math.max(shown - (item - 1), 0), 1);
+		const precision = hovered !== undefined || rated ? step / 2 : 0.25;
+		return Math.round(fill / precision) * precision;
+	}
+
+	function iconFor(snapped: number) {
+		if (snapped >= 1) return StarFilled;
+		if (snapped >= 0.75) return StarThreeQuarterRegular;
+		if (snapped >= 0.5) return StarHalfRegular;
+		if (snapped >= 0.25) return StarOneQuarterRegular;
+		return StarRegular;
+	}
+
+	function select(next: number) {
+		rated = true;
+		value = next;
+		onChange?.(next);
+	}
+
+	/** The value of the checked radio. Clicks select, the arrow keys included; a form reset unchecks every radio, which the binding reports as `null`. */
+	let checked = $derived<number | null>(checkedValue);
+
+	$effect(() => {
+		if (checked !== null) return;
+		rated = false;
+		value = 0;
+	});
+
+	function hover(event: PointerEvent & { currentTarget: HTMLInputElement }, item: number) {
+		invokeHandlers(event, [], [() => (hovered = item), onpointerenter]);
+	}
+</script>
+
+<!-- 
+	@component
+	A rating lets users give a value to an item, using a row of symbols such as stars. It supports half-filled items and four sizes.
+
+	- Usage:
+	```tsx
+	<script>
+		import { Rating } from 'fluentui-svelte';
+
+		let value = $state(3);
+	</script>
+
+	<Rating bind:value />
+	<Rating bind:value step={0.5} size="medium" />
+	```
+-->
+<div
+	{...wrapperAttributes}
+	class={['fs-rating', `size-${size}`, wrapperAttributes?.class]}
+	bind:this={wrapperRef}
+	role="radiogroup"
+	onpointerleave={(e) => invokeHandlers(e, [], [() => (hovered = undefined), wrapperAttributes?.onpointerleave])}
+	aria-labelledby={wrapperAttributes?.['aria-labelledby'] ?? labelContext?.labelId}
+	aria-label={wrapperAttributes?.['aria-label'] ??
+		(wrapperAttributes?.['aria-labelledby'] || labelContext ? undefined : 'Rating')}
+	aria-describedby={[wrapperAttributes?.['aria-describedby'], VALUE_ID].filter(Boolean).join(' ')}
+>
+	<span id={VALUE_ID} hidden>Current rating: {value} out of {_max}.</span>
+	{#each items as item (item)}
+		{@const fill = fillFor(item)}
+		<span class="rating-item">
+			{#if custom}
+				{@const Outline = iconOutline ?? StarRegular}
+				{@const Filled = iconFilled ?? StarFilled}
+				<span class={['rating-icon custom', { selected: fill > 0 }]} style="--rating-fill: {fill * 100}%">
+					<Outline aria-hidden="true" />
+					<span class="filled"><Filled aria-hidden="true" /></span>
+				</span>
+			{:else}
+				{@const Icon = iconFor(fill)}
+				<span class={['rating-icon', { selected: fill > 0 }]}><Icon aria-hidden="true" /></span>
+			{/if}
+			{#if step === 0.5}
+				<input
+					{...attributes}
+					{id}
+					{name}
+					class={['half-value', classes]}
+					type="radio"
+					value={item - 0.5}
+					aria-label={itemLabel(item - 0.5)}
+					bind:group={checked}
+					onclick={(e) => invokeHandlers(e, [], [() => value !== item - 0.5 && select(item - 0.5), onclick])}
+					onpointerenter={(e) => hover(e, item - 0.5)}
+				/>
+			{/if}
+			<input
+				{...attributes}
+				{name}
+				{id}
+				class={['full-value', classes]}
+				type="radio"
+				value={item}
+				aria-label={itemLabel(item)}
+				bind:group={checked}
+				onclick={(e) => invokeHandlers(e, [], [() => value !== item && select(item), onclick])}
+				onpointerenter={(e) => hover(e, item)}
+			/>
+		</span>
+	{/each}
+</div>
+
+<style>
+	.fs-rating {
+		--rating-size: 24px;
+		display: inline-flex;
+		align-items: center;
+		color: var(--fs-accent-fill-default);
+
+		&.size-small {
+			--rating-size: 12px;
+		}
+
+		&.size-medium {
+			--rating-size: 16px;
+		}
+
+		&.size-large {
+			--rating-size: 20px;
+		}
+
+		&:is([aria-invalid='true'], :has(input:user-invalid)) .rating-icon {
+			color: var(--fs-system-critical);
+		}
+
+		&:has(input:disabled) .rating-icon {
+			color: var(--fs-text-disabled);
+			& .filled {
+				color: inherit;
+			}
+		}
+	}
+
+	.rating-item {
+		display: inline-flex;
+		position: relative;
+		border-radius: var(--fs-control-border-radius);
+		padding: 2px;
+
+		&:has(input:focus-visible) {
+			box-shadow: var(--fs-focus-stroke-outer);
+		}
+
+		& input {
+			appearance: none;
+			position: absolute;
+			inset-block: 0;
+			inset-inline-start: 0;
+			margin: 0;
+			outline: none;
+			cursor: pointer;
+			inline-size: 100%;
+			block-size: 100%;
+		}
+
+		& .half-value {
+			z-index: 1;
+			inline-size: 50%;
+		}
+	}
+
+	.rating-icon {
+		display: inline-flex;
+		color: var(--fs-text-secondary);
+
+		&.selected {
+			color: var(--fs-accent-fill-default);
+		}
+
+		& :global(svg) {
+			inline-size: var(--rating-size);
+			block-size: var(--rating-size);
+		}
+
+		&.custom {
+			position: relative;
+
+			& .filled {
+				display: inline-flex;
+				position: absolute;
+				inset: 0;
+				color: var(--fs-accent-fill-default);
+				clip-path: inset(0 calc(100% - var(--rating-fill)) 0 0);
+
+				&:dir(rtl) {
+					clip-path: inset(0 0 0 calc(100% - var(--rating-fill)));
+				}
+			}
+		}
+	}
+</style>

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

@@ -0,0 +1,19 @@
+import type { RatingProps } from './types.ts';
+/**
+ * A rating lets users give a value to an item, using a row of symbols such as stars. It supports half-filled items and four sizes.
+ *
+ * - Usage:
+ * ```tsx
+ * <script>
+ * 	import { Rating } from 'fluentui-svelte';
+ *
+ * 	let value = $state(3);
+ * </script>
+ *
+ * <Rating bind:value />
+ * <Rating bind:value step={0.5} size="medium" />
+ * ```
+ */
+declare const Rating: import("svelte").Component<RatingProps, {}, "value" | "wrapperRef">;
+type Rating = ReturnType<typeof Rating>;
+export default Rating;

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

@@ -0,0 +1,44 @@
+import type { Component } from 'svelte';
+import type { HTMLAttributes, HTMLInputAttributes } from 'svelte/elements';
+/** @propsmith RatingProps */
+export type RatingProps = {
+    /** The current rating. Fractions are drawn in quarters until the user rates.
+     * @default 0
+     * @bindable
+     */
+    value?: number;
+    /** The number of items displayed. Must be a whole number greater than 1.
+     * @default 5
+     */
+    max?: number;
+    /** The precision of the rating. `0.5` allows half-filled items.
+     * @default 1
+     */
+    step?: 1 | 0.5;
+    /** The size of the rating items.
+     * @default 'extra-large'
+     */
+    size?: 'small' | 'medium' | 'large' | 'extra-large';
+    /** The icon of a filled item. Falls back to a filled star. Partially filled items are clipped, so it also works with half steps.
+     * @type Component
+     */
+    iconFilled?: Component;
+    /** The icon of an empty item. Falls back to an outlined star.
+     * @type Component
+     */
+    iconOutline?: Component;
+    /** Generates the accessible label of the radio input for a rating value.
+     * @default (rating) => `${rating}`
+     */
+    itemLabel?: (rating: number) => string;
+    /** Called when the user changes the rating. */
+    onChange?: (value: number) => void;
+    /** The DOM reference of the radiogroup element.
+     * @bindable
+     */
+    wrapperRef?: HTMLDivElement | null;
+    /** The attributes to spread on the radiogroup element. This is where its `aria-label`, `aria-labelledby`, `aria-invalid`, `id` and `class` go.
+     * @type HTMLAttributes
+     */
+    wrapperAttributes?: HTMLAttributes<HTMLDivElement>;
+} & Omit<HTMLInputAttributes, 'type' | 'value' | 'checked' | 'max' | 'step' | 'size' | 'style' | 'aria-label' | 'aria-invalid' | 'children'>;

package/dist/components/rating/types.js

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

package/dist/components/side-nav/docs/llms.md

@@ -0,0 +1,110 @@
+# SideNav
+
+App navigation built on ListView. SideNavItem renders an anchor by default. Use `as="button"` for actions, or `as="li"` / `as="div"` for content with multiple controls. The navigation owns no router: set href and active from your app's current route.
+
+## Usage
+
+```svelte
+<script>
+	import { AppWindow, AppSurface, SideNav, SideNavItem } from 'fluentui-svelte';
+	import { HomeRegular, FolderRegular, SettingsRegular } from 'fluentui-icons-svelte';
+</script>
+
+<AppWindow width={480} height={240}>
+	<SideNav header="Workspace">
+		<SideNavItem href="#home" label="Home" icon={HomeRegular} active />
+		<SideNavItem href="#documents" label="Documents" icon={FolderRegular} />
+		<SideNavItem href="#settings" label="Settings" icon={SettingsRegular} />
+	</SideNav>
+	<AppSurface style="padding: 1rem">Page content</AppSurface>
+</AppWindow>
+```
+
+SideNav also works on its own, in any container with a height. Use `bind:collapsed` to control it, `SideNavBranch` to nest items and the `footer` snippet to pin items to the bottom.
+
+## Modes and accessibility
+
+Docked navigation occupies layout space and collapses to an icon rail. Labels remain available to assistive technology. Items without icons show their initial in the rail. Opening a branch from the rail expands the navigation first.
+
+With `floating`, SideNav overlays AppWindow's body below its optional TitleBar. Closed floating navigation shows only the hamburger; opening it does not move page content. It is non-modal and does not trap focus. Escape, an outside pointer press, moving focus outside, and activating a SideNavItem close it. Set `closeOnSelect={false}` to keep it open after activation. A standalone floating SideNav needs a positioned parent.
+
+Inside an AppWindow whose TitleBar has a global navigation button (`TitleBarLeftControls globalNav`), that button expands and collapses the SideNav, follows its state in `aria-expanded`, and SideNav hides its own hamburger. Set `showToggle` to `true` to keep both, or to `false` to hide the hamburger and control it yourself (`getAppWindowContext().state.sideNav.setCollapsed`). While a floating navigation is open, the global button is not an outside press.
+
+The Button toggle exposes aria-expanded and aria-controls. SideNav is a named navigation landmark with native lists and links. The underlying ListView supplies arrow navigation, disabled-item handling and selection. Avoid menu/listbox roles for ordinary route navigation. There is no back button.
+
+## Custom content and footer
+
+Only two regions accept text, snippets or components: `topContent`, between the hamburger section and the list, and `footerContent`, after the list and before the pinned navigation footer. Strings render as text and are hidden in the compact rail. Snippets receive `{ collapsed, floating }`; components receive these as props, so they can render compact controls or hide their content. Use a snippet to supply other required component props.
+
+The header is plain text. SideNavItem uses its label or ordinary ListViewItem children markup. The `footer` snippet contains navigation entries and remains pinned while the main list scrolls. Compose real Menu, TextBox, Avatar and Button components in the two custom regions.
+
+## ListView customization
+
+`listViewProps` customizes every list of the navigation: the main one, the footer and the ones inside a SideNavBranch. Defaults are role="list", selectionMode="none" and navigationMode="items". Keep native list semantics when using branches. Selection can be enabled and bound through `selectedItems`, shared across all of them. Set each item's value when using selection.
+
+## Component Props (SideNav)
+
+<!-- DO NOT EDIT THIS SECTION (propsmith generated) -->
+<!-- props:SideNavProps -->
+
+| Name                                             | Type                                         | Default                 | Description                                                                                                                                                                                                                                                     |
+| ------------------------------------------------ | -------------------------------------------- | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ref` _bindable_                                 | `HTMLElement` &#124; `null`                  |                         | The DOM reference of the navigation landmark.                                                                                                                                                                                                                   |
+| `label`                                          | `string`                                     | `'Main navigation'`     | The accessible name of the navigation landmark.                                                                                                                                                                                                                 |
+| `collapsed` _bindable_                           | `boolean`                                    | `false`                 | Shows an icon rail when docked, or only the toggle when floating.                                                                                                                                                                                               |
+| `position`                                       | `'left'` &#124; `'right'`                    | `'left'`                | The side of the window the navigation is on. It mirrors in right-to-left layouts, and AppSurface rounds the corners that face it.                                                                                                                               |
+| `showToggle`                                     | `boolean`                                    | `Automatic`             | Whether the navigation shows its own hamburger toggle. By default it hides it when the title bar of its window has a global navigation button, which then controls the navigation. Set it to true to keep both, or to false to control the navigation yourself. |
+| `floating`                                       | `boolean`                                    | `false`                 | Overlays the content of a positioned parent instead of taking layout space. The overlay is non-modal.                                                                                                                                                           |
+| `width`                                          | `number` &#124; `string`                     | `200`                   | The expanded width. Numbers are pixels converted to rem; strings are CSS lengths.                                                                                                                                                                               |
+| `expandLabel`                                    | `string`                                     | `'Expand navigation'`   | The accessible label of the toggle while collapsed.                                                                                                                                                                                                             |
+| `collapseLabel`                                  | `string`                                     | `'Collapse navigation'` | The accessible label of the toggle while expanded.                                                                                                                                                                                                              |
+| `closeOnSelect`                                  | `boolean`                                    | `true`                  | Closes a floating panel after activating a SideNavItem.                                                                                                                                                                                                         |
+| `onCollapsedChange`                              | `(event: Event, collapsed: boolean) => void` |                         | Called when the user expands or collapses the navigation.                                                                                                                                                                                                       |
+| `selectedItems` _bindable_                       | `string[]`                                   |                         | The selection shared by every list in the navigation. Selection is off by default.                                                                                                                                                                              |
+| `listViewProps`                                  | `SideNavListViewProps`                       |                         | Overrides the defaults of every list in the navigation, the main one, the footer and the ones inside a SideNavBranch: native list semantics, no selection and one tab stop per item.                                                                            |
+| `header`                                         | `string`                                     |                         | The text heading beside the hamburger button. Hidden in the compact rail.                                                                                                                                                                                       |
+| `topContent`                                     | `string` &#124; `Snippet` &#124; `Component` |                         | Custom content between the hamburger section and the list. Text, snippets and components are supported. Renderers receive collapsed and floating; strings are hidden in the compact rail.                                                                       |
+| `footerContent`                                  | `string` &#124; `Snippet` &#124; `Component` |                         | Custom content after the scrolling list and before the pinned footer. Text, snippets and components are supported. Renderers receive collapsed and floating; strings are hidden in the compact rail.                                                            |
+| `footer`                                         | `Snippet`                                    |                         | Footer list items pinned to the bottom, outside the main list's scroll area.                                                                                                                                                                                    |
+| `children`                                       | `Snippet`                                    |                         | Main navigation items. Use SideNavItem and SideNavBranch.                                                                                                                                                                                                       |
+| `HTMLAttributes<HTMLElement>` without `children` |                                              |                         |                                                                                                                                                                                                                                                                 |
+
+<!-- /props:SideNavProps -->
+
+## Component Props (SideNavItem)
+
+<!-- DO NOT EDIT THIS SECTION (propsmith generated) -->
+<!-- props:SideNavItemProps -->
+
+| Name                                                                                                        | Type                                                                                          | Default | Description                                                                                    |
+| ----------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | ------- | ---------------------------------------------------------------------------------------------- |
+| `as`                                                                                                        | `'li'` &#124; `'a'` &#124; `'button'` &#124; `'div'`                                          | `'a'`   | The HTML tag. Links are the default; use button for actions and li or div for custom controls. |
+| `ref` _bindable_                                                                                            | `HTMLLIElement` &#124; `HTMLAnchorElement` &#124; `HTMLButtonElement` &#124; `HTMLDivElement` |         | The DOM reference of the item.                                                                 |
+| `label`                                                                                                     | `string`                                                                                      |         | The accessible label, also used as visible content when children are absent.                   |
+| `icon`                                                                                                      | `Snippet` &#124; `Component`                                                                  |         | The decorative icon shown in both expanded and collapsed modes.                                |
+| `children`                                                                                                  | `Snippet`                                                                                     |         | Optional item markup, following ListViewItem. The label is rendered when children are absent.  |
+| `shape`, `value`, `active`, `role`, `disabled`, `checkmark`, `onAction`, `onfocus` from `ListViewItemProps` |                                                                                               |         |                                                                                                |
+| HTML Attributes                                                                                             |                                                                                               |         |                                                                                                |
+
+<!-- /props:SideNavItemProps -->
+
+## Component Props (SideNavBranch)
+
+<!-- DO NOT EDIT THIS SECTION (propsmith generated) -->
+<!-- props:SideNavBranchProps -->
+
+| Name                                                                                                 | Type                                    | Default | Description                                                                                                                                                                                    |
+| ---------------------------------------------------------------------------------------------------- | --------------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `label`                                                                                              | `string`                                |         | The accessible label of the disclosure button. In the compact rail, its initial stands in when there is no icon.                                                                               |
+| `icon`                                                                                               | `Snippet` &#124; `Component`            |         | The decorative icon before the label.                                                                                                                                                          |
+| `expanded` _bindable_                                                                                | `boolean`                               | `false` | Whether the nested items are visible. Branches only expand or collapse and are never selectable. The compact rail reports a branch as collapsed, and opens the navigation when one is pressed. |
+| `onExpandedChange`                                                                                   | `(e: Event, expanded: boolean) => void` |         | Called when a user expands or collapses the branch.                                                                                                                                            |
+| `disabled`                                                                                           | `boolean`                               | `false` | Disables the disclosure button.                                                                                                                                                                |
+| `ref` _bindable_                                                                                     | `HTMLButtonElement`                     |         | The DOM reference of the native disclosure button. Additional HTML attributes, including class and id, also target this button.                                                                |
+| `wrapperRef` _bindable_                                                                              | `HTMLLIElement` &#124; `HTMLDivElement` |         | The DOM reference of the wrapper element, the list item that holds the button and the nested list.                                                                                             |
+| `wrapperAttributes`                                                                                  | `HTMLAttributes`                        |         | The attributes to spread on the wrapper element.                                                                                                                                               |
+| `shape`                                                                                              | `ListViewItemBranchProps['shape']`      |         | The disclosure button shape. Inherited from the list by default.                                                                                                                               |
+| `children`                                                                                           | `Snippet`                               |         | The nested SideNavItem and SideNavBranch content.                                                                                                                                              |
+| `HTMLButtonAttributes` without `children`, `role`, `type`, `value`, `aria-expanded`, `aria-controls` |                                         |         |                                                                                                                                                                                                |
+
+<!-- /props:SideNavBranchProps -->

package/dist/components/side-nav/side-nav-branch.svelte

@@ -0,0 +1,43 @@
+<script lang="ts">
+	import ListViewItemBranch from '../list-view/list-view-item-branch.svelte';
+	import SideNavList from './side-nav-list.svelte';
+	import { getSideNavContext } from './side-nav.js';
+	import type { SideNavBranchProps } from './types.js';
+
+	let {
+		ref = $bindable(null),
+		wrapperRef = $bindable(null),
+		expanded = $bindable(false),
+		label,
+		wrapperAttributes,
+		icon,
+		onclick,
+		children,
+		...attributes
+	}: SideNavBranchProps = $props();
+
+	const context = getSideNavContext();
+	// The rail hides the branch, so the branch reports collapsed there without losing its own state.
+	const visiblyExpanded = () => expanded && !context?.state.compact;
+</script>
+
+{#snippet initial()}<span>{label.slice(0, 1)}</span>{/snippet}
+
+<ListViewItemBranch
+	{...attributes}
+	{label}
+	wrapperAttributes={{ class: `fs-side-nav-branch ${wrapperAttributes?.class ?? ''}`, ...wrapperAttributes }}
+	icon={icon ?? (context?.state.compact ? initial : undefined)}
+	bind:ref
+	bind:wrapperRef
+	bind:expanded={visiblyExpanded, (value) => (expanded = value)}
+	onclick={(event) => {
+		onclick?.(event);
+		// A branch cannot open inside the rail, so the rail opens first.
+		if (!event.defaultPrevented) context?.methods.setCollapsed(event, false);
+	}}
+>
+	<SideNavList>
+		{@render children?.()}
+	</SideNavList>
+</ListViewItemBranch>

package/dist/components/side-nav/side-nav-branch.svelte.d.ts

@@ -0,0 +1,4 @@
+import type { SideNavBranchProps } from './types.ts';
+declare const SideNavBranch: import("svelte").Component<SideNavBranchProps, {}, "ref" | "wrapperRef" | "expanded">;
+type SideNavBranch = ReturnType<typeof SideNavBranch>;
+export default SideNavBranch;