fluentui-svelte 0.5.0 → 0.7.0

package/dist/components/label/label.svelte

@@ -1,52 +1,129 @@
 <script lang="ts">
+	import InfoRegular from 'fluentui-icons-svelte/InfoRegular.svelte';
+	import type { Attachment } from 'svelte/attachments';
 	import type { LabelProps } from './types.js';
+	import { PREFIX } from '../../internal/constants.js';
+	import { RenderSoC } from '../../internal/index.js';
+	import { Tooltip } from '../../index.js';
+	import { setLabelContext } from './label-context.js';
+
+	const FALLBACK_ID = $props.id();
 
 	let {
-		ref = $bindable(),
+		id = `${PREFIX}-label-${FALLBACK_ID}`,
+		for: htmlFor,
+		ref = $bindable(null),
+		as = 'div',
+		wrapperRef = $bindable(null),
+		wrapperAttributes,
 		class: classes,
 		disabled,
 		required,
 		size = 'medium',
 		weight = 'regular',
 		label = 'Label Element',
-		labelPosition = 'after',
+		labelPosition = 'above',
+		tooltipContent,
+		tooltipBadge = InfoRegular,
+		tooltipProps,
+		tooltipButtonAttributes,
 		children,
 		...attributes
 	}: LabelProps = $props();
+
+	/** The field inside the label, used to get its id */
+	let field = $state<() => string | null | undefined>();
+
+	const fieldId = $derived(htmlFor ?? `${id}-field`);
+
+	const INFO_ID = $derived(tooltipButtonAttributes?.id ?? `${id}-info`);
+
+	setLabelContext({
+		get labelId() {
+			return id;
+		},
+		get fieldId() {
+			return fieldId;
+		},
+		claim(report) {
+			if (field) return false;
+			field = report;
+			return true;
+		}
+	});
 </script>
 
-<label
+<svelte:element
+	this={as}
+	{...wrapperAttributes}
 	class={[
 		'fs-label',
 		`size-${size}`,
-		`weight-${weight}`,
-		classes,
 		{ disabled, required },
-		(labelPosition === 'above' || labelPosition === 'below') && 'column'
+		(labelPosition === 'above' || labelPosition === 'below') && 'column',
+		wrapperAttributes?.class
 	]}
-	bind:this={ref}
-	{...attributes}
+	bind:this={wrapperRef}
 >
 	{#if labelPosition === 'before' || labelPosition === 'above'}
-		<span>
-			{label}
-			{#if required}
-				<abbr title={required.message || label}>{required.abbr ?? '*'}</abbr>
-			{/if}
-		</span>
+		{@render labelText()}
 	{/if}
 
 	{@render children?.()}
 
 	{#if labelPosition === 'after' || labelPosition === 'below'}
-		<span>
-			{label}
-			{#if required}
-				<abbr title={required.message || label}>{required.abbr ?? '*'}</abbr>
-			{/if}
+		{@render labelText()}
+	{/if}
+</svelte:element>
+
+{#snippet labelText()}
+	{#if tooltipContent}
+		<!-- The badge sits beside the label text, not in it, or its name would join the name of the field. -->
+		<span class={['fs-label-heading', `size-${size}`]}>
+			{@render text()}
+			<Tooltip
+				withArrow
+				placement="top"
+				{...tooltipProps}
+				content={tooltipContent}
+				relationship="description"
+				children={badge}
+			/>
 		</span>
+	{:else}
+		{@render text()}
 	{/if}
-</label>
+{/snippet}
+
+{#snippet badge(attrs: { 'aria-describedby'?: string }, attach: Attachment)}
+	<button
+		type="button"
+		aria-label="More information"
+		{...tooltipButtonAttributes}
+		{...attrs}
+		id={INFO_ID}
+		aria-labelledby={tooltipButtonAttributes?.['aria-labelledby'] ?? `${id} ${INFO_ID}`}
+		class={['fs-label-info', tooltipButtonAttributes?.class]}
+		{@attach attach}
+	>
+		<RenderSoC SoC={tooltipBadge} />
+	</button>
+{/snippet}
+
+{#snippet text()}
+	<label
+		{...attributes}
+		{id}
+		for={field ? field() : fieldId}
+		class={['fs-label-text', `size-${size}`, `weight-${weight}`, classes]}
+		bind:this={ref}
+	>
+		{label}
+		{#if required}
+			<abbr aria-hidden="true" title={required.message || label}>{required.abbr ?? '*'}</abbr>
+		{/if}
+	</label>
+{/snippet}
 
 <style>
 	.fs-label {
@@ -58,24 +135,14 @@
 			align-items: flex-start;
 		}
 		&.size-small {
-			font-size: var(--fs-caption-font-size);
-			letter-spacing: 0.04em;
 			gap: 0.25rem;
 		}
 		&.size-medium {
-			font-size: var(--fs-body-font-size);
 			gap: 0.375rem;
 		}
 		&.size-large {
-			font-size: var(--fs-subtitle2-font-size);
 			gap: 0.5rem;
 		}
-		&.weight-regular {
-			font-weight: 400;
-		}
-		&.weight-semibold {
-			font-weight: 600;
-		}
 		&.disabled {
 			color: var(--fs-text-disabled);
 			pointer-events: none;
@@ -91,5 +158,61 @@
 				color: var(--fs-text-disabled);
 			}
 		}
+		& .fs-label-heading {
+			display: inline-flex;
+			align-items: center;
+			gap: 0.25rem;
+			&.size-small .fs-label-info {
+				font-size: 0.75rem;
+			}
+			&.size-large .fs-label-info {
+				font-size: 1.25rem;
+			}
+		}
+		& .fs-label-info {
+			display: inline-flex;
+			align-items: center;
+			padding: 0;
+			border: none;
+			border-radius: var(--fs-control-border-radius);
+			background: none;
+			color: var(--fs-text-secondary);
+			font-size: 1rem;
+			cursor: pointer;
+			&:hover {
+				color: var(--fs-text-primary);
+			}
+			&:focus-visible {
+				outline: 0.125rem var(--fs-focus-stroke-outer) solid;
+				outline-offset: 0.063rem;
+			}
+			& :global(svg) {
+				inline-size: 1em;
+				block-size: 1em;
+			}
+		}
+		& .fs-label-text {
+			&.size-small {
+				font-size: var(--fs-caption-font-size);
+				letter-spacing: 0.04em;
+			}
+			&.size-medium {
+				font-size: var(--fs-body-font-size);
+			}
+			&.size-large {
+				font-size: var(--fs-subtitle2-font-size);
+			}
+			&.weight-regular {
+				font-weight: 400;
+			}
+			&.weight-semibold {
+				font-weight: 600;
+			}
+		}
+		&:global(:has(*:user-invalid)) {
+			& .fs-label-text {
+				color: var(--fs-system-critical);
+			}
+		}
 	}
 </style>

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

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

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

@@ -1,8 +1,27 @@
-import type { HTMLLabelAttributes } from 'svelte/elements';
+import type { Component, Snippet } from 'svelte';
+import type { HTMLAttributes, HTMLButtonAttributes, HTMLLabelAttributes } from 'svelte/elements';
 import type { Sizes } from '../../types/index.js';
+import type { TooltipProps } from '../tooltip/types.ts';
 /** @propsmith LabelProps */
 export type LabelProps = {
-    /** The text of the label. Falls back to the rendered children.
+    /** The element used to wrap the label and its field.
+     * @default 'div'
+     */
+    as?: 'div' | 'span';
+    /** The field described by the label, rendered beside the label text.
+     * @type Snippet
+     */
+    children?: Snippet;
+    /** The DOM reference of the wrapper element.
+     * @type HTMLDivElement | HTMLSpanElement
+     * @bindable
+     */
+    wrapperRef?: HTMLDivElement | HTMLSpanElement | null;
+    /** The attributes to spread on the wrapper element.
+     * @type HTMLAttributes
+     */
+    wrapperAttributes?: HTMLAttributes<HTMLDivElement | HTMLSpanElement>;
+    /** The text of the label.
      * @default 'Label Element'
      */
     label?: string;
@@ -28,5 +47,30 @@ export type LabelProps = {
     /** The DOM reference of the label element.
      * @bindable
      */
-    ref?: HTMLLabelElement;
-} & HTMLLabelAttributes;
+    ref?: HTMLLabelElement | null;
+    /** The id of the label element. A control inside the label is named after it, including a picker whose visible control stands in for its native field.
+     * @default Generated
+     */
+    id?: string;
+    /** The id of the field the label is for. Without it, the label is for the first field inside it, which takes a generated id when it has none of its own. With `labelPosition` `before` or `above` and a field that has an id of its own, pass that id here, so the server renders the association too.
+     * @default The field inside
+     */
+    for?: string;
+    /** More about the field, in a tooltip shown from a badge after the label text, on hover and on focus. People cannot move into a tooltip, so keep links and buttons out of it.
+     * @type string | Snippet | Component
+     */
+    tooltipContent?: string | Snippet | Component;
+    /** What the badge that shows the tooltip displays. Only rendered with `tooltipContent`.
+     * @type Snippet | Component
+     * @default InfoRegular
+     */
+    tooltipBadge?: Snippet | Component;
+    /** The props to spread on the tooltip.
+     * @type TooltipProps
+     */
+    tooltipProps?: Omit<TooltipProps, 'content' | 'relationship' | 'children'>;
+    /** The attributes to spread on the button of the badge. Its name is the label text followed by its `aria-label`.
+     * @type HTMLButtonAttributes
+     */
+    tooltipButtonAttributes?: HTMLButtonAttributes;
+} & Omit<HTMLLabelAttributes, 'for'>;

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

@@ -20,7 +20,14 @@ The ListView is a component for rendering a set of vertically stacked items. The
 
 ## ListView API
 
-> **Best practices:** Please check the Fluent UI React List best practices for guidance.
+### Best practices
+
+- Keep lists that only display text out of the Tab sequence. Configure `navigationMode` on the outer ListView: use `items` for native link navigation and `composite` for selectable cards with secondary controls. Let the component manage item and control tabindex unless you opt out with `disableTabspot`.
+- With the default grid roles in selectable composite lists, the component wraps each row's content in one `gridcell` and manages navigation to its controls. No manual `gridcell` wrappers are needed.
+- Use `onAction` for an item's primary action and native buttons or links with `onclick` for secondary actions. Enter and Space both activate non-native actionable items; links retain native keyboard behavior. In composite selection rows, the checkmark changes selection independently, and secondary buttons and links do not trigger the row's action or selection.
+- Keep the default roles for flat selection widgets; they depend on both `selectionMode` and `navigationMode`. Match the HTML tags: `ul`/`ol` with `li` items, or `as="div"` on both a card list and its items.
+- Use ListViewItemBranch for expandable sublists. Branches are never selectable and manage their disclosure attributes and focus. Each nested list owns its selection. Set `role="list"` on each selectable list containing branches to preserve native list semantics.
+- Give selectable ListView widgets an accessible name with `aria-label` or `aria-labelledby`. Give navigation a named `nav` landmark and mark the current link with `aria-current="page"`. Use meaningful visible text or `aria-label` for controls, a descriptive branch `label`, and stable item `value` strings when using selection.
 
 ### As
 
@@ -32,10 +39,50 @@ Instead of setting this on every ListViewItem, you can set it here and every ite
 
 ### Navigation Mode
 
-This option allows you to set keyboard navigation based on your needs. For view-only data, you do not need to set this unless the items perform some action. If your items have multiple actionable elements within the ListViewItem, like buttons or menus, you can set this to composite.
+`items` keeps each item in the Tab order; `composite` gives the entire list one tab stop and lets Right enter an item's secondary controls. Selection uses listbox/option roles in items mode, or grid/row/gridcell roles in composite mode. Set `role="list"` on each selectable navigation list with sublists to preserve native list semantics; use `aria-current` on links to announce the current page.
+
+### Keyboard navigation
+
+Up/Down move between siblings and Home/End reach the ends of the current level. Right opens a collapsed branch; Right on an expanded branch enters its sublist. Left closes an expanded branch; Left on a collapsed branch or child returns to its parent. Escape closes the nearest branch and restores focus to its button. Right also enters a composite item's controls; Left/Right move between them, and Left from the first control returns to the row. Enter activates links; Enter and Space activate buttons and selectable items. `disableTabspot` opts out of arrow-key focus management. Each nested ListView owns its selection state, so selecting a child does not select its parent.
 
 ## Examples
 
+### Simple navigation
+
+Use native anchors inside a named navigation landmark. Under `ul` or `ol`, ListViewItem wraps anchors and buttons in `li` elements.
+
+```svelte
+<nav aria-label="Main navigation">
+	<ListView>
+		<ListViewItem as="a" href="/">Home</ListViewItem>
+		<ListViewItem as="a" href="/docs">Documentation</ListViewItem>
+		<ListViewItem as="a" href="/docs/components/list-view" aria-current="page">ListView</ListViewItem>
+	</ListView>
+</nav>
+```
+
+### Navigation with sublists
+
+Nest a ListView inside ListViewItemBranch. Branches are focusable disclosure buttons and never participate in selection. The component manages expanded state, aria-expanded, aria-controls, hidden content and focus restoration. Nested lists remain mounted when collapsed, preserving their selection. Hierarchy, indentation and keyboard groups are detected automatically; every nested list owns its selection. Use native list semantics: when selection is enabled, set `role="list"` on lists containing branches. Branches cannot be placed in listbox or grid lists. See the [WAI-ARIA disclosure pattern](https://www.w3.org/WAI/ARIA/apg/patterns/disclosure/).
+
+```svelte
+<script lang="ts">
+	import { ListView, ListViewItem, ListViewItemBranch } from 'fluentui-svelte';
+</script>
+
+<nav aria-label="Component navigation">
+	<ListView>
+		<ListViewItem as="a" href="/">Home</ListViewItem>
+		<ListViewItemBranch label="Components" expanded>
+			<ListView>
+				<ListViewItem as="a" href="/docs/components/button">Button</ListViewItem>
+				<ListViewItem as="a" href="/docs/components/checkbox">Checkbox</ListViewItem>
+			</ListView>
+		</ListViewItemBranch>
+	</ListView>
+</nav>
+```
+
 ### Value
 
 Sets the value of the current item. You must set this when using the ListView selection system or if items change dynamically.
@@ -49,7 +96,7 @@ This event is triggered when clicking or tapping the element. It executes the pr
 Use `selectionMode` (`single`, `multiselect`, or `extended`) to control how items are selected.
 
 ```svelte
-<ListView selectionMode="multiselect" selectedItems={['Apple']}>
+<ListView aria-label="Fruits" selectionMode="multiselect" selectedItems={['Apple']}>
 	{#each ['Apple', 'Banana', 'Cherry'] as item (item)}
 		<ListViewItem value={item}>{item}</ListViewItem>
 	{/each}
@@ -61,7 +108,7 @@ Use `selectionMode` (`single`, `multiselect`, or `extended`) to control how item
 In a multiselect list, a plain click selects only that item and Ctrl/Cmd + click toggles it. Set `toggleOnClick` to make a plain click toggle the item directly.
 
 ```svelte
-<ListView selectionMode="multiselect" toggleOnClick>
+<ListView aria-label="Fruits" selectionMode="multiselect" toggleOnClick>
 	{#each ['Apple', 'Banana', 'Cherry'] as item (item)}
 		<ListViewItem value={item}>{item}</ListViewItem>
 	{/each}
@@ -77,7 +124,7 @@ Add and configure a checkbox for the element. You can use the same props for the
 	let selected = $state(['Apple']);
 </script>
 
-<ListView selectionMode="multiselect" bind:selectedItems={selected}>
+<ListView aria-label="Fruits" selectionMode="multiselect" bind:selectedItems={selected}>
 	{#each ['Apple', 'Banana', 'Cherry'] as item (item)}
 		<ListViewItem value={item} checkmark={{}}>{item}</ListViewItem>
 	{/each}
@@ -88,7 +135,7 @@ Add and configure a checkbox for the element. You can use the same props for the
 
 ### Cards with a primary action
 
-With `navigationMode` set to `composite` and a `selectionMode`, every item is a row. Clicking it runs its primary action (`onAction`), the checkbox toggles its selection, and any button inside is a secondary action. Use `checkmark.wrapperAttributes.style` to place the checkbox where you need it, like the top-right corner of the card. Note: every actionable element inside this ListViewItem, except the checkbox, must call e.stopPropagation().
+With `navigationMode` set to `composite` and a `selectionMode`, every item is a row. Use `as="div"` for both the list and its card items to keep the HTML structure valid. Clicking a row runs its primary action (`onAction`), the checkbox toggles its selection, and any button inside is a secondary action. Use `checkmark.wrapperAttributes.style` to place the checkbox where you need it, like the top-right corner of the card. Secondary controls run their own actions without selecting the item or triggering its primary action.
 
 ```svelte
 <script>
@@ -106,13 +153,13 @@ With `navigationMode` set to `composite` and a `selectionMode`, every item is a
 	{#each cards as card (card.name)}
 		{#snippet install()}
 			<Button
-				onclick={(e) => {
-					e.stopPropagation();
+				onclick={() => {
 					lastAction = 'Installed ' + card.name;
 				}}>Install</Button
 			>
 		{/snippet}
 		<ListViewItem
+			as="div"
 			value={card.name}
 			checkmark={{ wrapperAttributes: { style: 'position: absolute; top: 0.5rem; right: 0.5rem; z-index: 2;' } }}
 			style="padding: 0"
@@ -135,18 +182,20 @@ With `navigationMode` set to `composite` and a `selectionMode`, every item is a
 <!-- DO NOT EDIT THIS SECTION (propsmith generated) -->
 <!-- props:ListViewProps -->
 
-| Name                       | Type                                                                  | Default     | Description                                                                                                                     |
-| -------------------------- | --------------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------- |
-| `selectionMode`            | `'none'` &#124; `'single'` &#124; `'multiselect'` &#124; `'extended'` | `'none'`    | How many items can be selected, and how the selection is made.                                                                  |
-| `navigationMode`           | `'items'` &#124; `'composite'`                                        | `'items'`   | Whether the list itself takes a single tab stop, or every item takes its own.                                                   |
-| `selectedItems` _bindable_ | `string[]`                                                            |             | The values of the selected items.                                                                                               |
-| `shape`                    | `'circular'` &#124; `'rounded'` &#124; `'square'`                     | `'rounded'` | The items can have a circular, rounded or square shape.                                                                         |
-| `onSelectionChange`        | `(e: Event, selectedItems: string[]` &#124; `[]) => void`             |             | Called whenever the selection changes.                                                                                          |
-| `toggleOnClick`            | `boolean`                                                             | `false`     | When `selectionMode` is `'multiselect'`, clicking an item toggles its selection directly instead of requiring Ctrl/Cmd + click. |
-| `as`                       | `'ul'` &#124; `'ol'` &#124; `'div'`                                   | `'ul'`      | The HTML element to render the list as.                                                                                         |
-| `ref` _bindable_           | `HTMLUListElement` &#124; `HTMLOListElement` &#124; `HTMLDivElement`  |             | The DOM reference of the list element.                                                                                          |
-| `disableTabspot`           | `boolean`                                                             | `false`     | Opts the list out of the tabspot focus management, to wire your own.                                                            |
-| HTML Attributes            |                                                                       |             |                                                                                                                                 |
+| Name                       | Type                                                                  | Default     | Description                                                                                                                                   |
+| -------------------------- | --------------------------------------------------------------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| `role`                     | `AriaRole`                                                            |             | Overrides the list role and the roles derived for its items. Use `list` for nested navigation with independent selection.                     |
+| `selectionMode`            | `'none'` &#124; `'single'` &#124; `'multiselect'` &#124; `'extended'` | `'none'`    | How many items can be selected, and how the selection is made.                                                                                |
+| `navigationMode`           | `'items'` &#124; `'composite'`                                        | `'items'`   | Whether the list itself takes a single tab stop, or every item takes its own.                                                                 |
+| `manageSpecialKeys`        | `boolean` &#124; `TabspotRootOptions['manageSpecialKeys']`            | `true`      | Which special keys Tabspot handles at the root. Set individual keys to leave Escape to an enclosing panel. Omitted keys in an object are off. |
+| `selectedItems` _bindable_ | `string[]`                                                            |             | The values of the selected items.                                                                                                             |
+| `shape`                    | `'circular'` &#124; `'rounded'` &#124; `'square'`                     | `'rounded'` | The items can have a circular, rounded or square shape.                                                                                       |
+| `onSelectionChange`        | `(e: Event, selectedItems: string[]` &#124; `[]) => void`             |             | Called whenever the selection changes.                                                                                                        |
+| `toggleOnClick`            | `boolean`                                                             | `false`     | When `selectionMode` is `'multiselect'`, clicking an item toggles its selection directly instead of requiring Ctrl/Cmd + click.               |
+| `as`                       | `'ul'` &#124; `'ol'` &#124; `'div'`                                   | `'ul'`      | The HTML element to render the list as.                                                                                                       |
+| `ref` _bindable_           | `HTMLUListElement` &#124; `HTMLOListElement` &#124; `HTMLDivElement`  |             | The DOM reference of the list element.                                                                                                        |
+| `disableTabspot`           | `boolean`                                                             | `false`     | Opts the list out of the tabspot focus management, to wire your own.                                                                          |
+| HTML Attributes            |                                                                       |             |                                                                                                                                               |
 
 <!-- /props:ListViewProps -->
 
@@ -155,18 +204,39 @@ With `navigationMode` set to `composite` and a `selectionMode`, every item is a
 <!-- DO NOT EDIT THIS SECTION (propsmith generated) -->
 <!-- props:ListViewItemProps -->
 
-| Name             | Type                                                               | Default | Description                                                                                |
-| ---------------- | ------------------------------------------------------------------ | ------- | ------------------------------------------------------------------------------------------ |
-| `as`             | `'li'` &#124; `'a'` &#124; `'div'`                                 | `'li'`  | The HTML element to render the item as.                                                    |
-| `shape`          | `'circular'` &#124; `'rounded'` &#124; `'square'`                  |         | The item can have a circular, rounded or square shape. Inherited from the list by default. |
-| `value`          | `string`                                                           |         | The value reported to the list when the item is selected. Falls back to a generated id.    |
-| `active`         | `boolean`                                                          |         | Renders the item in its pressed state.                                                     |
-| `role`           | `'treeitem'` &#124; `'menuitem'` &#124; `'option'` &#124; `'row'`  |         | The ARIA role of the item. Derived from the list by default.                               |
-| `disabled`       | `boolean`                                                          |         | Disables the user interaction.                                                             |
-| `checkmark`      | `CheckboxProps`                                                    |         | The props to spread on the checkbox rendered when the list is multiselect.                 |
-| `onAction`       | `(e: MouseEvent, value: string) => void`                           |         | Called when the item is clicked or activated with the keyboard.                            |
-| `onfocus`        | `(e: Event, value: string) => void`                                |         | Called when the item receives the focus.                                                   |
-| `ref` _bindable_ | `HTMLLIElement` &#124; `HTMLAnchorElement` &#124; `HTMLDivElement` |         | The DOM reference of the item element.                                                     |
-| HTML Attributes  |                                                                    |         |                                                                                            |
+| Name             | Type                                                                                          | Default | Description                                                                                                                                                                                                                                             |
+| ---------------- | --------------------------------------------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `as`             | `'li'` &#124; `'a'` &#124; `'button'` &#124; `'div'`                                          | `'li'`  | The HTML element to render the item as. Links and buttons are wrapped in a list item when the list renders as `ul` or `ol`. Use `li` or `div` for nested lists and content with multiple controls. Buttons cannot contain checkmarks or composite rows. |
+| `shape`          | `'circular'` &#124; `'rounded'` &#124; `'square'`                                             |         | The item can have a circular, rounded or square shape. Inherited from the list by default.                                                                                                                                                              |
+| `value`          | `string`                                                                                      |         | The value reported to the list when the item is selected. Falls back to a generated id.                                                                                                                                                                 |
+| `active`         | `boolean`                                                                                     |         | Renders the item in its pressed state.                                                                                                                                                                                                                  |
+| `role`           | `'treeitem'` &#124; `'menuitem'` &#124; `'option'` &#124; `'row'`                             |         | The ARIA role of the item. Derived from the list by default.                                                                                                                                                                                            |
+| `disabled`       | `boolean`                                                                                     |         | Disables the user interaction.                                                                                                                                                                                                                          |
+| `checkmark`      | `CheckboxProps`                                                                               |         | The props to spread on the checkbox rendered when the list is multiselect.                                                                                                                                                                              |
+| `onAction`       | `(e: MouseEvent, value: string) => void`                                                      |         | Called when the item is clicked or activated with the keyboard.                                                                                                                                                                                         |
+| `onfocus`        | `(e: Event, value: string) => void`                                                           |         | Called when the item receives the focus.                                                                                                                                                                                                                |
+| `ref` _bindable_ | `HTMLLIElement` &#124; `HTMLAnchorElement` &#124; `HTMLButtonElement` &#124; `HTMLDivElement` |         | The DOM reference of the item element.                                                                                                                                                                                                                  |
+| HTML Attributes  |                                                                                               |         |                                                                                                                                                                                                                                                         |
 
 <!-- /props:ListViewItemProps -->
+
+## ListViewItemBranch Props
+
+<!-- DO NOT EDIT THIS SECTION (propsmith generated) -->
+<!-- props:ListViewItemBranchProps -->
+
+| Name                                                                                                 | Type                                              | Default | Description                                                                                                                     |
+| ---------------------------------------------------------------------------------------------------- | ------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| `label`                                                                                              | `string`                                          |         | The accessible label rendered in the disclosure button.                                                                         |
+| `icon`                                                                                               | `Snippet` &#124; `Component`                      |         | The decorative icon before the label.                                                                                           |
+| `expanded` _bindable_                                                                                | `boolean`                                         | `false` | Whether the nested content is visible. Branches only expand or collapse and are never selectable.                               |
+| `onExpandedChange`                                                                                   | `(e: Event, expanded: boolean) => void`           |         | Called when a user expands or collapses the branch.                                                                             |
+| `disabled`                                                                                           | `boolean`                                         | `false` | Disables the disclosure button.                                                                                                 |
+| `shape`                                                                                              | `'circular'` &#124; `'rounded'` &#124; `'square'` |         | The disclosure button shape. Inherited from the list by default.                                                                |
+| `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.                                                                                |
+| `children`                                                                                           | `Snippet`                                         |         | Nested ListView content, kept mounted while collapsed to preserve its selection.                                                |
+| `HTMLButtonAttributes` without `children`, `role`, `type`, `value`, `aria-expanded`, `aria-controls` |                                                   |         |                                                                                                                                 |
+
+<!-- /props:ListViewItemBranchProps -->