fluentui-svelte 0.5.0 → 0.7.0

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

@@ -1,19 +1,29 @@
 <script lang="ts" generics="Tag extends 'ul' | 'ol' | 'div' = 'ul'">
 	import type { ListViewContext, ListViewProps, ListViewDOM } from './types.js';
-	import { getRole, TAG, setListViewContext } from './utils.js';
-	import { getTabspotAttributes } from 'tabspot';
+	import {
+		attachTabspot,
+		getListViewContext,
+		getListViewItemContext,
+		getRole,
+		LIST_VIEW_SKIP,
+		TAG,
+		setListViewContext
+	} from './utils.js';
+	import { getTabspotAttributes, type TabspotNodeOptions } from 'tabspot';
 
 	let {
 		as = 'ul' as Tag,
-		ref = $bindable(),
+		ref = $bindable(null),
 		selectionMode = 'none',
 		navigationMode = 'items',
+		manageSpecialKeys = true,
 		shape = 'rounded',
 		selectedItems = $bindable([]),
 		onSelectionChange,
 		disableTabspot = false,
 		toggleOnClick = false,
 		children,
+		class: classes,
 		...attributes
 	}: ListViewProps<Tag> = $props();
 
@@ -21,40 +31,69 @@
 	 * The tag the invariant rules over. The markup renders it through here, so it is checked
 	 * during SSR and on every prop update rather than only once on mount.
 	 */
+	const itemContext = getListViewItemContext();
 	const _as = $derived.by(() => {
 		if (!TAG.includes(as)) throw new Error(`Invalid tag: ${as}. Must be one of ${TAG.join(', ')}`);
+		if (itemContext?.as === 'a' || itemContext?.as === 'button') {
+			throw new Error('Nested ListView must be inside a li or div ListViewItem, outside links and buttons.');
+		}
 		return as;
 	});
 
-	const ROLE = $derived(getRole(as, selectionMode, navigationMode));
+	const parent = getListViewContext();
+	const tabspotDisabled = $derived(disableTabspot || !!parent?.config.disableTabspot);
+	const ROLE = $derived(attributes.role ?? getRole(as, selectionMode, navigationMode));
 
 	const MULTISELECTABLE = $derived(selectionMode === 'multiselect' || selectionMode === 'extended');
 
-	const tabspotAttrs = $derived(
-		!disableTabspot &&
-			getTabspotAttributes({
-				root: {
-					manageSpecialKeys: true
-				},
-				mover: {
-					axis: 'vertical',
-					items: '.fs-list-view-item'
+	const tabspotConfig: TabspotNodeOptions | undefined = $derived(
+		tabspotDisabled
+			? undefined
+			: {
+					...(parent
+						? { grouper: { enterDirection: 'right', exitDirection: 'left' } }
+						: { root: { manageSpecialKeys } }),
+					mover: {
+						axis: 'vertical',
+						items:
+							'.fs-list-view-item[data-list-view-interactive], .fs-list-view-item:not([data-list-view-interactive]) :is(a[href], button), .fs-list-view-item-branch-trigger',
+						visibilityAware: 'Visible',
+						skip: LIST_VIEW_SKIP,
+						...(!parent && { activation: { mode: 'focus', roving: navigationMode === 'composite' } })
+					}
 				}
-			})
 	);
+	const tabspotAttrs = $derived(tabspotConfig && getTabspotAttributes(tabspotConfig));
 
 	let anchorIndex: number | null = $state(null);
 
 	let items: {
 		id: string;
-		value: string;
-		disabled: boolean;
+		getItem: () => { value: string; disabled: boolean; element: HTMLElement | null };
 	}[] = $state([]);
 
+	// The item that holds the tab stop in the server HTML, before Tabspot runs. Plain, since only the first render reads it.
+	let tabStopId: string | null = null;
+
 	const CONTEXT: ListViewContext = $state({
 		config: {
 			get shape() {
 				return shape;
+			},
+			get as() {
+				return as;
+			},
+			get selectionMode() {
+				return selectionMode;
+			},
+			get role() {
+				return ROLE;
+			},
+			get disableTabspot() {
+				return tabspotDisabled;
+			},
+			get roving() {
+				return !parent && navigationMode === 'composite';
 			}
 		},
 		state: {
@@ -73,19 +112,27 @@
 		},
 		events: null,
 		methods: {
+			claimTabStop: (id) => (tabStopId ??= id) === id,
 			handleSelection: (e: MouseEvent, value: string, toggle = false) => {
 				if (selectionMode === 'none') return;
 
-				const itemIndex = items.findIndex((item) => item.value === value);
+				// Registration order can differ from the DOM after keyed items are reordered.
+				const orderedItems = items
+					.map((item) => item.getItem())
+					.sort((a, b) => {
+						if (!a.element || !b.element) return 0;
+						return a.element.compareDocumentPosition(b.element) & Node.DOCUMENT_POSITION_FOLLOWING ? -1 : 1;
+					});
+				const itemIndex = orderedItems.findIndex((item) => item.value === value);
 				if (itemIndex === -1) return;
 
-				const item = items[itemIndex];
+				const item = orderedItems[itemIndex];
 				if (item.disabled) return;
 
 				if (selectionMode === 'extended' && e.shiftKey && anchorIndex !== null) {
 					const start = Math.min(anchorIndex, itemIndex);
 					const end = Math.max(anchorIndex, itemIndex);
-					const rangeValues = items
+					const rangeValues = orderedItems
 						.slice(start, end + 1)
 						.filter((i) => !i.disabled)
 						.map((i) => i.value);
@@ -101,13 +148,13 @@
 				}
 				onSelectionChange?.(e, selectedItems);
 			},
-			registerItem: (id: string, value: string, disabled: boolean) => {
-				items.push({ id, value, disabled });
+			registerItem: (id, getItem) => {
+				items.push({ id, getItem });
 			},
 			unregisterItem: (id: string) => {
 				items = items.filter((item) => item.id !== id);
 			},
-			getChildrenRole: (_tag: 'li' | 'a' | 'div') => {
+			getChildrenRole: (_tag: 'li' | 'a' | 'button' | 'div') => {
 				if (ROLE === 'grid') return 'row';
 				if (ROLE === 'listbox') return 'option';
 				return _tag !== 'li' ? 'listitem' : undefined;
@@ -120,12 +167,13 @@
 
 <svelte:element
 	this={_as}
+	{...attributes}
 	bind:this={ref as ListViewDOM[Tag]}
-	class="fs-list-view"
+	class={['fs-list-view', classes]}
 	role={ROLE}
-	aria-multiselectable={MULTISELECTABLE || undefined}
+	aria-multiselectable={((ROLE === 'grid' || ROLE === 'listbox') && MULTISELECTABLE) || undefined}
 	{...tabspotAttrs}
-	{...attributes}
+	{@attach attachTabspot(tabspotConfig)}
 >
 	{@render children?.()}
 </svelte:element>

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

@@ -1,10 +1,15 @@
 import type { CheckboxProps } from '../checkbox/types.ts';
 import type { FSContext } from '../../internal/index.js';
 import type { PolymorphicProps, Shapes } from '../../types/index.js';
+import type { AriaRole, HTMLAttributes, HTMLButtonAttributes } from 'svelte/elements';
+import type { Component, Snippet } from 'svelte';
+import type { TabspotRootOptions } from 'tabspot';
 export type SelectionMode = 'none' | 'single' | 'multiselect' | 'extended';
 export type NavigationMode = 'items' | 'composite';
 /** @propsmith ListViewProps */
 export type ListViewProps<T extends 'ul' | 'ol' | 'div'> = {
+    /** Overrides the list role and the roles derived for its items. Use `list` for nested navigation with independent selection. */
+    role?: AriaRole;
     /** How many items can be selected, and how the selection is made.
      * @default 'none'
      */
@@ -13,6 +18,11 @@ export type ListViewProps<T extends 'ul' | 'ol' | 'div'> = {
      * @default 'items'
      */
     navigationMode?: NavigationMode;
+    /** 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.
+     * @type boolean | TabspotRootOptions['manageSpecialKeys']
+     * @default true
+     */
+    manageSpecialKeys?: TabspotRootOptions['manageSpecialKeys'];
     /** The values of the selected items.
      * @bindable
      */
@@ -36,7 +46,7 @@ export type ListViewProps<T extends 'ul' | 'ol' | 'div'> = {
      * @type HTMLUListElement | HTMLOListElement | HTMLDivElement
      * @bindable
      */
-    ref?: ListViewDOM[T];
+    ref?: ListViewDOM[T] | null;
     /** Opts the list out of the tabspot focus management, to wire your own.
      * @default false
      */
@@ -48,12 +58,14 @@ export type ListViewDOM = {
     div: HTMLDivElement;
 };
 /** @propsmith ListViewItemProps */
-export type ListViewItemProps<T extends 'li' | 'a' | 'div' = 'li'> = {
+export type ListViewItemProps<T extends 'li' | 'a' | 'button' | 'div' = 'li'> = {
     /** The HTML element to render the item as.
-     * @type 'li' | 'a' | 'div'
+     * 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.
+     * @type 'li' | 'a' | 'button' | 'div'
      * @default 'li'
      */
-    as?: T | 'a' | 'div';
+    as?: T | 'a' | 'button' | 'div';
     /** The item can have a circular, rounded or square shape. Inherited from the list by default. */
     shape?: Shapes;
     /** The value reported to the list when the item is selected. Falls back to a generated id. */
@@ -73,18 +85,63 @@ export type ListViewItemProps<T extends 'li' | 'a' | 'div' = 'li'> = {
     /** Called when the item receives the focus. */
     onfocus?: (e: Event, value: string) => void;
     /** The DOM reference of the item element.
-     * @type HTMLLIElement | HTMLAnchorElement | HTMLDivElement
+     * @type HTMLLIElement | HTMLAnchorElement | HTMLButtonElement | HTMLDivElement
      * @bindable
      */
     ref?: ListViewItemDOM[T] | null;
-} & PolymorphicProps<T>;
+} & PolymorphicProps<T, 'onfocus'>;
 export type ListViewItemDOM = {
     li: HTMLLIElement;
     a: HTMLAnchorElement;
+    button: HTMLButtonElement;
     div: HTMLDivElement;
 };
+/** @propsmith ListViewItemBranchProps */
+export type ListViewItemBranchProps = {
+    /** The accessible label rendered in the disclosure button. */
+    label: string;
+    /** The decorative icon before the label.
+     * @type Snippet | Component
+     */
+    icon?: Snippet | Component;
+    /** Whether the nested content is visible. Branches only expand or collapse and are never selectable.
+     * @default false
+     * @bindable
+     */
+    expanded?: boolean;
+    /** Called when a user expands or collapses the branch. */
+    onExpandedChange?: (e: Event, expanded: boolean) => void;
+    /** Disables the disclosure button.
+     * @default false
+     */
+    disabled?: boolean;
+    /** The disclosure button shape. Inherited from the list by default. */
+    shape?: Shapes;
+    /** The DOM reference of the native disclosure button. Additional HTML attributes, including class and id, also target this button.
+     * @type HTMLButtonElement
+     * @bindable
+     */
+    ref?: HTMLButtonElement | null;
+    /** The DOM reference of the wrapper element, the list item that holds the button and the nested list.
+     * @type HTMLLIElement | HTMLDivElement
+     * @bindable
+     */
+    wrapperRef?: HTMLLIElement | HTMLDivElement | null;
+    /** The attributes to spread on the wrapper element.
+     * @type HTMLAttributes
+     */
+    wrapperAttributes?: HTMLAttributes<HTMLLIElement | HTMLDivElement>;
+    /** Nested ListView content, kept mounted while collapsed to preserve its selection. */
+    children?: Snippet;
+} & Omit<HTMLButtonAttributes, 'children' | 'role' | 'type' | 'value' | 'aria-expanded' | 'aria-controls'>;
 export type ListViewContextConfig = {
     shape: Shapes;
+    as: 'ul' | 'ol' | 'div';
+    selectionMode: SelectionMode;
+    role: AriaRole | undefined;
+    disableTabspot: boolean;
+    /** Whether the list keeps a single tab stop that the arrow keys move. */
+    roving: boolean;
 };
 export type ListViewContextState = {
     selectedItems: string[];
@@ -92,8 +149,14 @@ export type ListViewContextState = {
 };
 export type ListViewContextMethods = {
     handleSelection: (e: MouseEvent, value: string, toggle?: boolean) => void;
-    getChildrenRole: (tag: 'li' | 'a' | 'div') => 'listitem' | 'option' | 'row' | undefined;
-    registerItem: (id: string, value: string, disabled: boolean) => void;
+    getChildrenRole: (tag: 'li' | 'a' | 'button' | 'div') => 'listitem' | 'option' | 'row' | undefined;
+    registerItem: (id: string, getItem: () => {
+        value: string;
+        disabled: boolean;
+        element: HTMLElement | null;
+    }) => void;
     unregisterItem: (id: string) => void;
+    /** True for the first item to ask: it holds the tab stop until Tabspot takes the stop over on mount. */
+    claimTabStop: (id: string) => boolean;
 };
 export type ListViewContext = FSContext<ListViewContextConfig, ListViewContextState, null, ListViewContextMethods>;

package/dist/components/list-view/utils.d.ts

@@ -1,6 +1,16 @@
 import type { ListViewContext, NavigationMode, SelectionMode } from './types.ts';
+import type { Attachment } from 'svelte/attachments';
+import { type TabspotNodeOptions, type TabspotEventListener, type TabspotInstance } from 'tabspot';
 export declare const COMPONENT_NAME = "fslist-view-";
 export declare const TAG: string[];
 export declare const ITEM_TAG: string[];
+export declare const LIST_VIEW_SKIP = "[disabled], [aria-disabled=\"true\"], [hidden], [hidden] *, [inert], [inert] *, [aria-hidden=\"true\"], [aria-hidden=\"true\"] *";
+export declare const getListViewItemContext: () => {
+    readonly as: "li" | "a" | "button" | "div";
+} | null, setListViewItemContext: (context: {
+    readonly as: "li" | "a" | "button" | "div";
+}) => void;
+/** Register roots mounted after the provider starts, and release managed focus on updates/unmount. */
+export declare function attachTabspot(config: TabspotNodeOptions | undefined, onNavigate?: TabspotEventListener, instance?: TabspotInstance): Attachment<HTMLElement>;
 export declare function getRole(tag: 'ul' | 'ol' | 'div', selectionMode: SelectionMode, navigationMode: NavigationMode): 'grid' | 'listbox' | 'list' | undefined;
 export declare const getListViewContext: () => ListViewContext | null, setListViewContext: (context: ListViewContext) => void;

package/dist/components/list-view/utils.js

@@ -1,8 +1,24 @@
 import { PREFIX } from '../../internal/constants.js';
 import { createFSContext } from '../../internal/index.js';
+import { setTabspotAttributes } from 'tabspot';
 export const COMPONENT_NAME = `${PREFIX}list-view-`;
 export const TAG = ['ul', 'ol', 'div'];
-export const ITEM_TAG = ['li', 'a', 'div'];
+export const ITEM_TAG = ['li', 'a', 'button', 'div'];
+export const LIST_VIEW_SKIP = '[disabled], [aria-disabled="true"], [hidden], [hidden] *, [inert], [inert] *, [aria-hidden="true"], [aria-hidden="true"] *';
+export const [getListViewItemContext, setListViewItemContext] = createFSContext();
+/** Register roots mounted after the provider starts, and release managed focus on updates/unmount. */
+export function attachTabspot(config, onNavigate, instance) {
+    return (element) => {
+        if (!config)
+            return;
+        const result = setTabspotAttributes({ element, config });
+        const detach = onNavigate && (result.ok ? (result.instance ?? instance) : undefined)?.subscribe(onNavigate);
+        return () => {
+            detach?.();
+            setTabspotAttributes({ element, config: {} });
+        };
+    };
+}
 export function getRole(tag, selectionMode, navigationMode) {
     if (selectionMode !== 'none') {
         return navigationMode === 'composite' ? 'grid' : 'listbox';

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

@@ -21,6 +21,8 @@ Other components that can be used within the menu include:
 - `MenuItemCheckbox`: A menu item that can be checked or unchecked.
 - `MenuItemSwitch`: A menu item that can be toggled on or off.
 - `MenuItemRadio`: A menu item that can be selected as part of a group of radio items.
+- `MenuCommandBar`: A row of icon-only commands placed at the top or at the bottom of the menu, with an optional overflow submenu.
+- `MenuCommandBarItem`: A square, icon-only command of a MenuCommandBar, with a label that names it and shows as its tooltip.
 
 ## Usage
 
@@ -87,7 +89,7 @@ To correctly attach events to the trigger element, you should wrap the element w
 		{#snippet children({ state, menuTriggerProps, primaryButtonProps })}
 			<SplitButton
 				bind:menuTriggerRef={state.ref}
-				{menuTriggerProps}
+				menuTriggerProps={{ ...menuTriggerProps, 'aria-label': 'More options' }}
 				primaryButtonProps={{ onclick: () => alert('Primary action'), ...primaryButtonProps }}
 			>
 				Primary Action
@@ -103,6 +105,51 @@ To correctly attach events to the trigger element, you should wrap the element w
 </Menu>
 ```
 
+### Menu with a command bar
+
+A command bar flyout pairs a row of square, icon-only primary commands with the items of the menu. Place a `MenuCommandBar` at the top or at the bottom of the `MenuList` and set its `position` to match. Fill it with `MenuCommandBarItem`, each with an `icon` and a `label` that names it and shows as its tooltip. The `overflow` snippet adds a "more" button at the end of the row that opens the secondary commands in a submenu.
+
+Left and Right move along the bar. Up and Down move between the bar and the items of the menu.
+
+```svelte
+<Menu>
+	<MenuTrigger>
+		{#snippet children({ state, menuTriggerProps })}
+			<Button bind:ref={state.ref} {...menuTriggerProps}>Commands on top</Button>
+		{/snippet}
+	</MenuTrigger>
+	<MenuPopover>
+		<MenuList>
+			<!-- position="bottom" when the bar comes after the items -->
+			<MenuCommandBar>
+				<MenuCommandBarItem icon={CutRegular} label="Cut" />
+				<MenuCommandBarItem icon={CopyRegular} label="Copy" />
+				<MenuCommandBarItem icon={ClipboardPasteRegular} label="Paste" />
+				{#snippet overflow()}
+					<MenuItem>Select all</MenuItem>
+					<MenuItem>Rename</MenuItem>
+				{/snippet}
+			</MenuCommandBar>
+			<MenuItem>Open</MenuItem>
+			<MenuItem>Open with</MenuItem>
+			<MenuItem>Properties</MenuItem>
+		</MenuList>
+	</MenuPopover>
+</Menu>
+```
+
+By default every command is a square that shows only its icon. `showLabels` shows the label of every command below its icon, and `showDividers` draws a divider between every two commands; with either of them the commands share the width of the bar evenly.
+
+```svelte
+<MenuCommandBar showLabels showDividers>
+	<MenuCommandBarItem icon={CutRegular} label="Cut" />
+	<MenuCommandBarItem icon={CopyRegular} label="Copy" />
+	<MenuCommandBarItem icon={EditRegular} label="Rename" />
+	<MenuCommandBarItem icon={ShareRegular} label="Share" />
+	<MenuCommandBarItem icon={DeleteRegular} label="Delete" />
+</MenuCommandBar>
+```
+
 ## Context Menu
 
 This variant of the `MenuTrigger` component allows you to create context menus that open on right-click. You can specify the element to which the context menu should be attached using the `ref` prop. If no element is provided, it will attach to the `document.body` by default.
@@ -147,8 +194,8 @@ This variant of the `MenuTrigger` component allows you to create context menus t
 
 | Name              | Type                                 | Default | Description                                              |
 | ----------------- | ------------------------------------ | ------- | -------------------------------------------------------- |
-| `ref`             | `HTMLElement`                        |         | The element used to position the popover.                |
-| `open` _bindable_ | `boolean`                            |         | Controls the open state of the popover.                  |
+| `ref`             | `HTMLElement` &#124; `null`          |         | The element used to position the popover.                |
+| `open` _bindable_ | `boolean` &#124; `null`              |         | Controls the open state of the popover.                  |
 | `keepMounted`     | `boolean`                            | `false` | Keeps the popover mounted in the DOM while it is closed. |
 | `placement`       | `ComputePositionConfig['placement']` |         | Where the popover is positioned relative to its trigger. |
 | `positionConfig`  | `ComputePositionConfig`              |         | The position configuration handed over to floating-ui.   |
@@ -190,13 +237,13 @@ This variant of the `MenuTrigger` component allows you to create context menus t
 <!-- DO NOT EDIT THIS SECTION (propsmith generated) -->
 <!-- props:MenuItemActionableProps -->
 
-| Name                                   | Type      | Default | Description                                                                                |
-| -------------------------------------- | --------- | ------- | ------------------------------------------------------------------------------------------ |
-| `checked` _bindable_                   | `boolean` |         | Whether the item is checked.                                                               |
-| `value`                                | `string`  | `id`    | The value reported to the menu when the item is checked. Falls back to the id of the item. |
-| `name`                                 | `string`  | `id`    | The group of items this one belongs to. Falls back to the id of the item.                  |
-| `MenuItemProps` without `href`         |           |         |                                                                                            |
-| `ComponentProps<typeof Button<'div'>>` |           |         |                                                                                            |
+| Name                           | Type                    | Default | Description                                                                                |
+| ------------------------------ | ----------------------- | ------- | ------------------------------------------------------------------------------------------ |
+| `checked` _bindable_           | `boolean` &#124; `null` |         | Whether the item is checked.                                                               |
+| `value`                        | `string`                | `id`    | The value reported to the menu when the item is checked. Falls back to the id of the item. |
+| `name`                         | `string`                | `id`    | The group of items this one belongs to. Falls back to the id of the item.                  |
+| `MenuItemProps` without `href` |                         |         |                                                                                            |
+| `ButtonProps<'button'>`        |                         |         |                                                                                            |
 
 <!-- /props:MenuItemActionableProps -->
 
@@ -205,10 +252,46 @@ This variant of the `MenuTrigger` component allows you to create context menus t
 <!-- DO NOT EDIT THIS SECTION (propsmith generated) -->
 <!-- props:MenuGroupProps -->
 
-| Name             | Type             | Default | Description                             |
-| ---------------- | ---------------- | ------- | --------------------------------------- |
-| `ref` _bindable_ | `HTMLDivElement` |         | The DOM reference of the group element. |
-| `header`         | `string`         |         | The label of the group.                 |
-| `children`       | `Snippet`        |         | The items of the group.                 |
+| Name             | Type                           | Default | Description                             |
+| ---------------- | ------------------------------ | ------- | --------------------------------------- |
+| `ref` _bindable_ | `HTMLDivElement` &#124; `null` |         | The DOM reference of the group element. |
+| `header`         | `string`                       |         | The label of the group.                 |
+| `children`       | `Snippet`                      |         | The items of the group.                 |
 
 <!-- /props:MenuGroupProps -->
+
+## Component Props (MenuCommandBar)
+
+<!-- DO NOT EDIT THIS SECTION (propsmith generated) -->
+<!-- props:MenuCommandBarProps -->
+
+| Name                                                        | Type                           | Default          | Description                                                                                                    |
+| ----------------------------------------------------------- | ------------------------------ | ---------------- | -------------------------------------------------------------------------------------------------------------- |
+| `ref` _bindable_                                            | `HTMLDivElement` &#124; `null` |                  | The DOM reference of the command bar element.                                                                  |
+| `position`                                                  | `'top'` &#124; `'bottom'`      | `'top'`          | Where the bar sits in the menu. A bar at the top has its divider below it, and one at the bottom has it above. |
+| `label`                                                     | `string`                       | `'Commands'`     | The accessible name of the group of commands.                                                                  |
+| `overflowLabel`                                             | `string`                       | `'More options'` | The accessible name of the button that opens the overflow.                                                     |
+| `overflow`                                                  | `Snippet`                      |                  | The secondary commands. When present, a "more" button at the end of the bar opens them in a submenu.           |
+| `showLabels`                                                | `boolean`                      | `false`          | Shows the label of every command below its icon. Without labels, every command is a square.                    |
+| `showDividers`                                              | `boolean`                      | `false`          | Draws a divider between every two commands.                                                                    |
+| `children`                                                  | `Snippet`                      |                  | The primary commands, as `MenuCommandBarItem`s.                                                                |
+| `HTMLAttributes<HTMLDivElement>` without `children`, `role` |                                |                  |                                                                                                                |
+
+<!-- /props:MenuCommandBarProps -->
+
+## Component Props (MenuCommandBarItem)
+
+<!-- DO NOT EDIT THIS SECTION (propsmith generated) -->
+<!-- props:MenuCommandBarItemProps -->
+
+| Name                                                                        | Type                              | Default | Description                                                                                                                                          |
+| --------------------------------------------------------------------------- | --------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ref` _bindable_                                                            | `HTMLButtonElement` &#124; `null` |         | The DOM reference of the button element.                                                                                                             |
+| `icon`                                                                      | `Snippet` &#124; `Component`      |         | The icon of the command.                                                                                                                             |
+| `label`                                                                     | `string`                          |         | The name of the command. Without visible labels it is the accessible name of the button and shows as its tooltip; with them it shows below the icon. |
+| `disabled`                                                                  | `boolean`                         |         | Disables the user interaction.                                                                                                                       |
+| `onclick`                                                                   | `(e: MouseEvent) => void`         |         | Called when the command is activated. The menu closes afterwards, unless it persists on item activation.                                             |
+| `AriaAttributes` without `aria-label`                                       |                                   |         |                                                                                                                                                      |
+| `id`, `class`, `onkeydown`, `onfocus`, `onblur` from `HTMLButtonAttributes` |                                   |         |                                                                                                                                                      |
+
+<!-- /props:MenuCommandBarItemProps -->

package/dist/components/menu/menu-command-bar-item.svelte

@@ -0,0 +1,61 @@
+<script lang="ts">
+	import { Button } from '../../index.js';
+	import { RenderSoC } from '../../internal/index.js';
+	import { getMenuCommandBarContext, getMenuContext, COMPONENT_NAME as MENU_COMPONENT_NAME } from './menu.svelte.js';
+	import type { MenuCommandBarItemProps } from './types.js';
+
+	let {
+		ref = $bindable(null),
+		icon,
+		label,
+		disabled,
+		onclick,
+		class: classes,
+		...attributes
+	}: MenuCommandBarItemProps = $props();
+
+	const context = getMenuContext();
+
+	if (!context) throw new Error(`No MenuContext found for ${MENU_COMPONENT_NAME}.`);
+
+	const { toggle } = context.methods;
+
+	const commandBarContext = getMenuCommandBarContext();
+
+	// A visible label names the button itself, a hidden one names it and shows as its tooltip.
+	const showLabel = $derived(!!commandBarContext?.showLabels);
+</script>
+
+<!--
+@component
+
+A command of a `MenuCommandBar`: a square icon whose label names it and shows as its tooltip, or the icon with the label below it when the bar shows labels.
+
+- Usage:
+  ```tsx
+    <MenuCommandBar>
+      <MenuCommandBarItem icon={CutRegular} label="Cut" onclick={cut} />
+    </MenuCommandBar>
+  ```
+-->
+<Button
+	{...attributes}
+	bind:ref
+	{disabled}
+	role="menuitem"
+	appearance="subtle"
+	aria-label={showLabel ? undefined : label}
+	title={showLabel ? undefined : label}
+	class={['fs-menu-command-bar-item', classes]}
+	onclick={(e: MouseEvent) => {
+		if (disabled) return;
+		onclick?.(e);
+		if (!context.config.persistOnItemActivation) toggle(e);
+	}}
+>
+	<RenderSoC SoC={icon} args={{ class: 'fs-menu-command-bar-item-icon' }} />
+	{#if showLabel}
+		<span class="fs-menu-command-bar-item-label">{label}</span>
+	{/if}
+</Button>
+<!-- The layout is drawn by MenuCommandBar, which styles the overflow button the same way. -->

package/dist/components/menu/menu-command-bar-item.svelte.d.ts

@@ -0,0 +1,14 @@
+import type { MenuCommandBarItemProps } from './types.ts';
+/**
+ * A command of a `MenuCommandBar`: a square icon whose label names it and shows as its tooltip, or the icon with the label below it when the bar shows labels.
+ *
+ * - Usage:
+ * ```tsx
+ *   <MenuCommandBar>
+ *     <MenuCommandBarItem icon={CutRegular} label="Cut" onclick={cut} />
+ *   </MenuCommandBar>
+ * ```
+ */
+declare const MenuCommandBarItem: import("svelte").Component<MenuCommandBarItemProps, {}, "ref">;
+type MenuCommandBarItem = ReturnType<typeof MenuCommandBarItem>;
+export default MenuCommandBarItem;