@scion/components 22.2.0 → 22.4.0

package/types/scion-components-menu.d.ts

@@ -0,0 +1,1922 @@
+import * as _angular_core from '@angular/core';
+import { Injector, Signal, ElementRef, Binding, Provider, ViewContainerRef } from '@angular/core';
+import { OneOf, MaybeArray, Disposable, RequireOne } from '@scion/toolkit/types';
+import { ComponentType } from '@angular/cdk/portal';
+import { MaybeSignal, SciComponentDescriptor } from '@scion/components/common';
+import { Translatable } from '@scion/components/text';
+import * as _scion_components_menu from '@scion/components/menu';
+
+interface SciMenubarFactory {
+    addMenu(descriptor: SciMenubarMenuDescriptor, menuFactoryFn: (menu: SciMenuFactory) => void): this;
+}
+interface SciMenubarMenuDescriptor {
+    name?: `menuitem:${string}`;
+    label: MaybeSignal<Translatable>;
+    visible?: MaybeSignal<boolean>;
+    cssClass?: string | string[];
+    attributes?: {
+        [name: string]: string;
+    };
+    menu?: SciMenuDescriptor['menu'];
+}
+
+/**
+ * Represents a menu contribution contributed via {@link contributeMenu}.
+ */
+interface SciMenuContribution {
+    /** Type of this contribution, indicating whether contributing to a menu, toolbar, or menubar. */
+    type: 'menu' | 'toolbar' | 'menubar';
+    /** Factory function to instantiate menu items of this contribution. */
+    factoryFn: SciMenuFactoryFnLike;
+    /** Minimal context required by this contribution. */
+    requiredContext: Map<string, unknown>;
+    /** Position where to insert menu items of this contribution. */
+    position?: SciMenuContributionPositionLike;
+    /** Instant when this contribution was registered. */
+    contributionInstant: number;
+    /** Arbitrary metadata associated with this contribution. */
+    metadata: {
+        [key: string]: unknown;
+    };
+}
+/**
+ * Controls contribution to a menu location.
+ */
+interface SciMenuContributionOptions {
+    /**
+     * Declares a minimal required context.
+     *
+     * The contribution is only applied if the context of the menu location contains at least the specified key/value pairs.
+     * Context requirements can be defined using explicit values or an asterisk (`*`) to require any value for a given context key.
+     *
+     * @example - Contribute only for administrators within an active project context
+     * ```ts
+     * requiredContext: new Map()
+     *   .set('userRole', 'admin')
+     *   .set('activeProjectId', '*')
+     * ```
+     *
+     * A required context can also be provided at the injector level using {@link provideMenuContextProvider}, for example, at the component, route, or application level,
+     * and is available to menus contributed in the scope of this injector. The inherited context can be overridden or extended. Setting a context entry to `undefined` clears it.
+     */
+    requiredContext?: Map<string, unknown>;
+    /**
+     * Specifies the injector used to register the contribution. Defaults to the current injection context.
+     *
+     * The contribution is disposed when the passed injector is destroyed.
+     */
+    injector?: Injector;
+    /**
+     * Allows associating arbitrary metadata with the contribution.
+     *
+     * @docs-private Not public API. Used by frameworks integrating the SCION Menu API. Applications should not use this property.
+     */
+    metadata?: {
+        [key: string]: unknown;
+    };
+    /**
+     * Specifies an instant used to maintain a stable contribution order when the contribution is replaced, e.g., on context change.
+     *
+     * @docs-private Not public API. Used by frameworks integrating the SCION Menu API. Applications should not use this property.
+     */
+    contributionInstant?: number;
+}
+/**
+ * Describes location and position of a menu contribution.
+ */
+type SciMenuContributionLocation = {
+    location: `menu:${string}`;
+} & SciMenuContributionPosition;
+/**
+ * Describes location and position of a toolbar contribution.
+ */
+type SciToolbarContributionLocation = {
+    location: `toolbar:${string}`;
+} & SciToolbarContributionPosition;
+/**
+ * Describes location and position of a menubar contribution.
+ */
+type SciMenubarContributionLocation = {
+    location: `menubar:${string}`;
+} & SciMenubarContributionPosition;
+/**
+ * Describes location and position of a menu, toolbar, or menubar contribution.
+ */
+type SciMenuContributionLocationLike = SciMenuContributionLocation | SciToolbarContributionLocation | SciMenubarContributionLocation;
+/**
+ * Controls where to insert a contribution into a menu. Can be at the beginning, at the end, or relative to a menu item or menu group.
+ */
+type SciMenuContributionPosition = OneOf<{
+    before?: `menuitem:${string}` | `menu:${string}`;
+    after?: `menuitem:${string}` | `menu:${string}`;
+    position?: 'start' | 'end';
+}>;
+/**
+ * Controls where to insert a contribution into a toolbar. Can be at the beginning, at the end, or relative to a toolbar item or toolbar group.
+ */
+type SciToolbarContributionPosition = OneOf<{
+    before?: `menuitem:${string}` | `toolbar:${string}`;
+    after?: `menuitem:${string}` | `toolbar:${string}`;
+    position?: 'start' | 'end';
+}>;
+/**
+ * Controls where to insert a contribution into a menubar. Can be at the beginning, at the end, or relative to a menu item.
+ */
+type SciMenubarContributionPosition = OneOf<{
+    before?: `menu:${string}`;
+    after?: `menu:${string}`;
+    position?: 'start' | 'end';
+}>;
+/**
+ * Controls where to insert a contribution into a menu, toolbar, or menubar.
+ */
+type SciMenuContributionPositionLike = SciMenuContributionPosition | SciToolbarContributionPosition | SciMenubarContributionPosition;
+/**
+ * Signature of a function used to add menu items to a menu.
+ *
+ * The menu calls this function with a {@link SciMenuFactory} that provides methods for populating it.
+ * The menu context is passed as the second argument, a key/value map that describes the environment of the menu.
+ *
+ * The function runs within a reactive context, running again when tracked signals change.
+ * Most menu item properties accept a value or signal. For properties that can change, prefer setting the property as a signal over tracking it manually to prevent this function from re-running.
+ *
+ * The function can call `inject` to get required dependencies from the root injector. Registering a {@link provideMenuInjectionContextProvider} allows providing additional tokens for dependency injection.
+ *
+ * @experimental since 22.3.0; API and behavior may change in any version without notice.
+ */
+type SciMenuFactoryFn = (menu: SciMenuFactory, context: Map<string, unknown>) => void;
+/**
+ * Signature of a function used to add tools to a {@link SciToolbarComponent}.
+ *
+ * The toolbar calls this function with a {@link SciToolbarFactory} that provides methods for populating it.
+ * The toolbar context is passed as the second argument, a key/value map that describes the environment of the toolbar.
+ *
+ * The function runs within a reactive context, running again when tracked signals change.
+ * Most menu item properties accept a value or signal. For properties that can change, prefer setting the property as a signal over tracking it manually to prevent this function from re-running.
+ *
+ * The function can call `inject` to get required dependencies from the root injector. Registering a {@link provideMenuInjectionContextProvider} allows providing additional tokens for dependency injection.
+ *
+ * @experimental since 22.3.0; API and behavior may change in any version without notice.
+ */
+type SciToolbarFactoryFn = (toolbar: SciToolbarFactory, context: Map<string, unknown>) => void;
+/**
+ * Signature of a function used to add tools to a {@link SciMenubarComponent}.
+ *
+ * The menubar calls this function with a {@link SciMenubarFactory} that provides methods for populating it.
+ * The menubar context is passed as the second argument, a key/value map that describes the environment of the menubar.
+ *
+ * The function runs within a reactive context, running again when tracked signals change.
+ * Most menu item properties accept a value or signal. For properties that can change, prefer setting the property as a signal over tracking it manually to prevent this function from re-running.
+ *
+ * The function can call `inject` to get required dependencies from the root injector. Registering a {@link provideMenuInjectionContextProvider} allows providing additional tokens for dependency injection.
+ *
+ * @experimental since 22.3.0; API and behavior may change in any version without notice.
+ */
+type SciMenubarFactoryFn = (menubar: SciMenubarFactory, context: Map<string, unknown>) => void;
+/**
+ * Represents a {@link SciMenuFactoryFn}, {@link SciToolbarFactoryFn}, or {@link SciMenubarFactoryFn}.
+ */
+type SciMenuFactoryFnLike = SciMenuFactoryFn | SciToolbarFactoryFn | SciMenubarFactoryFn;
+
+/**
+ * INPUTS FOR DESCRIPTION: https://www.electronjs.org/docs/latest/api/menu-item
+ *
+ * TODO [menu] describe (shared)
+ */
+interface SciMenuItem {
+    type: 'menu-item';
+    name?: `menuitem:${string}`;
+    labelText?: Signal<string>;
+    labelComponent?: SciComponentDescriptor;
+    iconLigature?: Signal<string>;
+    iconComponent?: SciComponentDescriptor;
+    control?: SciComponentDescriptor;
+    tooltip?: Signal<string>;
+    accelerator?: SciKeyboardAccelerator;
+    disabled?: Signal<boolean>;
+    visible?: Signal<boolean>;
+    checked?: Signal<boolean>;
+    active?: Signal<boolean>;
+    actions?: SciMenuItemLike[];
+    matchesFilter?: (filter: string) => boolean;
+    position?: SciMenuContributionPositionLike;
+    visualMenuIndicator?: boolean;
+    cssClass?: string[];
+    attributes?: {
+        [name: string]: string;
+    };
+    onSelect?: () => Promise<boolean>;
+    menu?: {
+        name?: `menu:${string}`;
+        width?: string;
+        minWidth?: string;
+        maxWidth?: string;
+        maxHeight?: string;
+        filter?: SciMenuFilterConfig<Signal<Translatable>>;
+        children: SciMenuItemLike[];
+    };
+}
+interface SciMenuGroup {
+    type: 'group';
+    name?: `menu:${string}` | `toolbar:${string}`;
+    label?: Signal<string>;
+    collapsible?: {
+        collapsed: boolean;
+    };
+    glyphArea?: false;
+    disabled?: Signal<boolean>;
+    visible?: Signal<boolean>;
+    position?: SciMenuContributionPositionLike;
+    actions?: SciMenuItemLike[];
+    children: SciMenuItemLike[];
+    cssClass?: string[];
+}
+type SciMenuItemLike = SciMenuItem | SciMenuGroup;
+
+/**
+ * Installs accelerators for menu items contributed to the given location matching the specified context.
+ *
+ * An accelerator maps a physical key combination (key combined with modifiers such as `Ctrl`, `Shift`, or `Alt`) to an application action,
+ * enabling users to trigger an action without using a pointer device.
+ *
+ * Context and accelerator targets are inherited from the current injector hierarchy, but can be overridden via {@link SciMenuAcceleratorOptions.context} and {@link SciMenuAcceleratorOptions.target} options.
+ *
+ * This function must be called within an injection context, or an explicit {@link Injector} passed. Destroying the injection context uninstalls the accelerators.
+ *
+ * @param location - Specifies the menu, toolbar, or menubar for which to install accelerators.
+ * @param options - Controls the installation of accelerators.
+ * @returns Handle to uninstall the accelerators.
+ *
+ * @experimental since 22.3.0; API and behavior may change in any version without notice.
+ */
+declare function installMenuAccelerators(location: `menu:${string}` | `toolbar:${string}` | `menubar:${string}`, options?: SciMenuAcceleratorOptions): Disposable;
+/**
+ * Controls the installation of accelerators.
+ */
+interface SciMenuAcceleratorOptions {
+    /**
+     * Specifies DOM elements on which to install menu accelerators. Defaults to {@link Document}.
+     *
+     * Alternatively, accelerator targets can be provided at the injector level using {@link provideMenuAcceleratorTargetProvider}, for example, at the component, route, or application level,
+     * and are available to accelerators installed in the scope of this injector. Inherited targets can be overridden.
+     */
+    target?: MaybeArray<Element | ElementRef<Element>>;
+    /**
+     * Controls in which context to install menu accelerators.
+     *
+     * Menu contributions may declare a required context. Only accelerators of contributions matching the context are installed.
+     *
+     * A context can also be provided at the injector level using {@link provideMenuContextProvider}, for example, at the component, route, or application level,
+     * and is available to accelerators installed in the scope of this injector. The inherited context can be overridden or extended. Setting a context entry to `undefined` clears it.
+     */
+    context?: Map<string, unknown>;
+    /**
+     * Specifies the injector used to install accelerators. Defaults to the current injection context.
+     *
+     * Accelerators are uninstalled when the injector is destroyed.
+     */
+    injector?: Injector;
+    /**
+     * Specifies metadata available to the operation.
+     *
+     * @docs-private Not public API. Used by frameworks integrating the SCION Menu API. Applications should not use this property.
+     */
+    metadata?: {
+        [key: string]: unknown;
+    };
+}
+/**
+ * Represents a keyboard accelerator to match specific keystrokes or key combinations.
+ *
+ * An accelerator maps a physical key combination (key combined with modifiers such as `Ctrl`, `Shift`, or `Alt`) to an application action,
+ * enabling users to trigger an action without using a pointer device.
+ */
+interface SciKeyboardAccelerator {
+    /**
+     * Specifies the key of the accelerator.
+     *
+     * @see https://developer.mozilla.org/en-US/docs/Web/API/UI_Events/Keyboard_event_key_values
+     */
+    key: string;
+    /**
+     * Indicates whether the `Ctrl` key (or `Cmd` key on macOS) must be pressed.
+     */
+    ctrl?: boolean;
+    /**
+     * Indicates whether the `Shift` key must be pressed.
+     */
+    shift?: boolean;
+    /**
+     * Indicates whether the `Alt` key (or `Opt` key on macOS) must be pressed.
+     */
+    alt?: boolean;
+    /**
+     * Specifies the physical location of the key on the keyboard.
+     *
+     * - `numpad`: Keys on the numeric keypad.
+     * - `left`: Left-side modifier keys.
+     * - `right`: Right-side modifier keys.
+     *
+     * @see https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/location
+     */
+    location?: 'numpad' | 'left' | 'right';
+}
+
+/**
+ * Factory used for adding items to a {@link SciToolbarComponent}.
+ *
+ * A toolbar is a horizontal or vertical container that provides quick access to context-related tools.
+ * It can contain buttons, split buttons, toggles, menus, and other controls, with related items grouped together.
+ *
+ * The methods of this factory return a reference to this factory, enabling method chaining.
+ */
+interface SciToolbarFactory {
+    /**
+     * Adds a button or toggle to the toolbar.
+     *
+     * A toolbar button typically has an icon, a tooltip, and an accelerator. Clicking the button invokes {@link SciToolbarButtonDescriptor.onSelect}.
+     *
+     * ```ts
+     * contributeMenu('toolbar:main', toolbar => toolbar
+     *   .addToolbarButton({icon: 'undo', accelerator: {ctrl: true, key: 'Z'}, tooltip: 'Undo', onSelect: () => console.log('Undo')})
+     *   .addToolbarButton({icon: 'redo', accelerator: {ctrl: true, key: 'Y'}, tooltip: 'Redo', onSelect: () => console.log('Redo')}),
+     * );
+     * ```
+     *
+     * ##### Toggle Button
+     *
+     * Setting {@link SciToolbarButtonDescriptor.checked} configures the button as a toggle button.
+     *
+     * ```ts
+     * const bold = signal(true);
+     * const italic = signal(false);
+     *
+     * contributeMenu('toolbar:main', toolbar => toolbar
+     *   .addToolbarButton({icon: 'format_bold', checked: bold, accelerator: {ctrl: true, shift: true, key: 'B'}, tooltip: 'Bold', onSelect: () => bold.update(bold => !bold)})
+     *   .addToolbarButton({icon: 'format_italic', checked: italic, accelerator: {ctrl: true, shift: true, key: 'I'}, tooltip: 'Italic', onSelect: () => italic.update(italic => !italic)}),
+     * );
+     * ```
+     *
+     * ##### Allow for Relative Positioning
+     *
+     * Assigning a name allows other contributions to be positioned relative to this button.
+     *
+     * ```ts
+     * contributeMenu('toolbar:main', toolbar => toolbar
+     *   .addToolbarButton({
+     *     name: 'menuitem:undo', // <--- Gives the button a name
+     *     icon: 'undo',
+     *     onSelect: () => console.log('Undo'),
+     *   }),
+     * );
+     * ```
+     *
+     * Use that name to contribute before or after the toolbar button.
+     *
+     * ```ts
+     * contributeMenu({location: 'toolbar:main', after: 'menuitem:undo'}, toolbar => toolbar
+     *   .addToolbarButton({icon: 'save', onSelect: () => console.log('Save')}),
+     * );
+     * ```
+     *
+     * @param descriptor - Configures the appearance and behavior of the button.
+     * @returns A reference to this factory, enabling method chaining.
+     */
+    addToolbarButton(descriptor: SciToolbarButtonDescriptor): this;
+    /**
+     * Adds a split button to the toolbar.
+     *
+     * A split button consists of two parts: a primary action button and a menu button that opens a menu with related actions.
+     * Clicking the primary action button invokes {@link SciToolbarButtonDescriptor.onSelect}.
+     *
+     * Pass a descriptor to configure the primary action button and the appearance of the menu.
+     * To add menu items to the menu, pass a menu factory function as the second argument. The menu calls this function with a {@link SciMenuFactory} that provides methods for populating it.
+     *
+     * ```ts
+     * contributeMenu('toolbar:main', toolbar => toolbar
+     *   .addToolbarSplitButton({
+     *       icon: 'content_paste',
+     *       tooltip: 'Paste',
+     *       accelerator: {ctrl: true, key: 'V'},
+     *       onSelect: () => console.log('Paste'),
+     *     }, menu => menu
+     *       .addMenuItem({icon: 'image', label: 'Paste Rich Text', onSelect: () => console.log('Paste Rich Text')})
+     *       .addMenuItem({icon: 'article', label: 'Paste Text', onSelect: () => console.log('Paste Text')})
+     *       .addMenuItem({icon: 'link', label: 'Paste URL', onSelect: () => console.log('Paste URL')}),
+     *   ),
+     * );
+     * ```
+     *
+     * ##### Allow for Separate Menu Contributions
+     *
+     * As an alternative to defining the menu items inline, assign the menu a name, allowing for separate contributions to the menu using {@link contributeMenu}.
+     *
+     * ```ts
+     * contributeMenu('toolbar:main', toolbar => toolbar
+     *   .addToolbarSplitButton({
+     *     icon: 'content_paste',
+     *     tooltip: 'Paste',
+     *     accelerator: {ctrl: true, key: 'V'},
+     *     onSelect: () => console.log('Paste'),
+     *     menu: {name: 'menu:paste-options'}, // <--- Gives the menu a name
+     *   }),
+     * );
+     * ```
+     *
+     * Use that name to contribute to the menu.
+     *
+     * ```ts
+     * contributeMenu('menu:paste-options', menu => menu
+     *   .addMenuItem({icon: 'image', label: 'Paste Rich Text', onSelect: () => console.log('Paste Rich Text')})
+     *   .addMenuItem({icon: 'article', label: 'Paste Text', onSelect: () => console.log('Paste Text')})
+     *   .addMenuItem({icon: 'link', label: 'Paste URL', onSelect: () => console.log('Paste URL')}),
+     * );
+     * ```
+     *
+     * ##### Toggle Split Button
+     *
+     * Setting {@link SciToolbarButtonDescriptor.checked} configures the split button as a toggle button.
+     *
+     * ```ts
+     * const underlined = signal<'solid' | 'dashed' | 'dotted' | false>(false);
+     *
+     * contributeMenu('toolbar:main', toolbar => toolbar
+     *   .addToolbarSplitButton({
+     *       icon: 'format_underlined',
+     *       checked: computed(() => underlined() !== false), // <--- Sets the button's checked state
+     *       tooltip: 'Underlined',
+     *       accelerator: {ctrl: true, shift: true, key: 'U'},
+     *       onSelect: () => underlined.update(underlined => underlined ? false : 'solid'),
+     *     }, menu => menu
+     *       .addMenuItem({label: 'Solid', onSelect: () => underlined.set('solid')})
+     *       .addMenuItem({label: 'Dashed', onSelect: () => underlined.set('dashed')})
+     *       .addMenuItem({label: 'Dotted', onSelect: () => underlined.set('dotted')}),
+     *   ),
+     * );
+     * ```
+     *
+     * ##### Allow for Relative Positioning
+     *
+     * Assigning the split button a name allows other contributions to be positioned relative to it.
+     *
+     * ```ts
+     * contributeMenu('toolbar:main', toolbar => toolbar
+     *   .addToolbarSplitButton({
+     *     name: 'menuitem:paste', // <--- Gives the split button a name
+     *     icon: 'content_paste',
+     *     onSelect: () => console.log('Paste'),
+     *   }),
+     * );
+     * ```
+     *
+     * Use that name to contribute before or after the split button.
+     *
+     * ```ts
+     * contributeMenu({location: 'toolbar:main', after: 'menuitem:paste'}, toolbar => toolbar
+     *   .addToolbarButton({icon: 'save', onSelect: () => console.log('Save')}),
+     * );
+     * ```
+     *
+     * @param descriptor - Configures the appearance and behavior of the split button and its menu.
+     * @param menuFactoryFn - Optional factory function to add menu items to the menu.
+     * @returns A reference to this factory, enabling method chaining.
+     */
+    addToolbarSplitButton(descriptor: SciToolbarButtonDescriptor & {
+        menu?: SciMenuDescriptor['menu'];
+    }, menuFactoryFn?: (menu: SciMenuFactory) => void): this;
+    /**
+     * Adds a menu to the toolbar.
+     *
+     * Pass a descriptor to configure the menu button and the appearance of the menu.
+     * By default, renders a visual menu indicator, which can be disabled via the {@link SciToolbarMenuDescriptor.visualMenuIndicator} property.
+     *
+     * To add menu items to the menu, pass a menu factory function as the second argument. The menu calls this function with a {@link SciMenuFactory} that provides methods for populating it.
+     *
+     * ```ts
+     * contributeMenu('toolbar:main', toolbar => toolbar
+     *   .addToolbarMenu({icon: 'folder', tooltip: 'File'}, menu => menu
+     *     .addMenuItem({icon: 'save', label: 'Save', accelerator: {ctrl: true, key: 'S'}, onSelect: () => console.log('Save')})
+     *     .addMenuItem({icon: 'print', label: 'Print', accelerator: {ctrl: true, key: 'P'}, onSelect: () => console.log('Print')})
+     *     .addMenu({icon: 'file_download', label: 'Export As...'}, menu => menu
+     *       .addMenuItem({icon: 'picture_as_pdf', label: 'PDF Document', onSelect: () => console.log('PDF Document')})
+     *       .addMenuItem({icon: 'table_view', label: 'Excel Spreadsheet', onSelect: () => console.log('Excel Spreadsheet')}),
+     *     ),
+     *   ),
+     * );
+     * ```
+     *
+     * ##### Allow for Separate Menu Contributions
+     *
+     * As an alternative to defining the menu items inline, assign the menu (or submenu) a name, allowing for separate contributions to the menu using {@link contributeMenu}.
+     *
+     * ```ts
+     * contributeMenu('toolbar:main', toolbar => toolbar
+     *   .addToolbarMenu({
+     *     icon: 'folder',
+     *     tooltip: 'File',
+     *     menu: {name: 'menu:file'}, // <--- Gives the menu a name
+     *   }),
+     * );
+     * ```
+     *
+     * Use that name to contribute to the menu.
+     *
+     * ```ts
+     * contributeMenu('menu:file', menu => menu
+     *   .addMenuItem({icon: 'save', label: 'Save', accelerator: {ctrl: true, key: 'S'}, onSelect: () => console.log('Save')})
+     *   .addMenuItem({icon: 'print', label: 'Print', accelerator: {ctrl: true, key: 'P'}, onSelect: () => console.log('Print')})
+     *   .addMenu({icon: 'file_download', label: 'Export As...'}, menu => menu
+     *     .addMenuItem({icon: 'picture_as_pdf', label: 'PDF Document', onSelect: () => console.log('PDF Document')})
+     *     .addMenuItem({icon: 'table_view', label: 'Excel Spreadsheet', onSelect: () => console.log('Excel Spreadsheet')}),
+     *   ),
+     * );
+     * ```
+     *
+     * ##### Allow for Relative Positioning
+     *
+     * Assigning the menu button a name allows other contributions to be positioned relative to it.
+     *
+     * ```ts
+     * contributeMenu('toolbar:main', toolbar => toolbar
+     *   .addToolbarMenu({
+     *     name: 'menuitem:file', // <--- Gives the menu button a name
+     *     icon: 'folder',
+     *     tooltip: 'File',
+     *   }),
+     * );
+     * ```
+     *
+     * Use that name to contribute before or after the menu button.
+     *
+     * ```ts
+     * contributeMenu({location: 'toolbar:main', after: 'menuitem:file'}, toolbar => toolbar
+     *   .addToolbarButton({icon: 'save', onSelect: () => console.log('Save')}),
+     * );
+     * ```
+     *
+     * @param descriptor - Configures the appearance and behavior of the menu button and its menu.
+     * @param menuFactoryFn - Optional factory function to add menu items to the menu.
+     * @returns A reference to this factory, enabling method chaining.
+     */
+    addToolbarMenu(descriptor: SciToolbarMenuDescriptor, menuFactoryFn?: (menu: SciMenuFactory) => void): this;
+    /**
+     * Adds a component to the toolbar, allowing for custom toolbar items like a filter field.
+     *
+     * The control can be any component. Data can be passed to the component via {@link SciToolbarControlDescriptor.bindings}.
+     * Because the component is not a button, it does not support a selection handler, checked state, or disabled state.
+     *
+     * ```ts
+     * contributeMenu('toolbar:main', toolbar => toolbar
+     *   .addToolbarControl({
+     *     component: FilterFieldComponent,
+     *     bindings: [inputBinding('placeholder', signal('Filter items...'))],
+     *   }),
+     * );
+     * ```
+     *
+     * ##### Allow for Relative Positioning
+     *
+     * Assigning a name allows other contributions to be positioned relative to this control.
+     *
+     * ```ts
+     * contributeMenu('toolbar:main', toolbar => toolbar
+     *   .addToolbarControl({
+     *     name: 'menuitem:filter', // <--- Gives the toolbar control a name
+     *     component: FilterFieldComponent,
+     *   }),
+     * );
+     * ```
+     *
+     * Use that name to contribute before or after the toolbar control.
+     *
+     * ```ts
+     * contributeMenu({location: 'toolbar:main', after: 'menuitem:filter'}, toolbar => toolbar
+     *   .addToolbarButton({icon: 'save', onSelect: () => console.log('Save')}),
+     * );
+     * ```
+     *
+     * @param descriptor - Specifies the component and its inputs.
+     * @returns A reference to this factory, enabling method chaining.
+     */
+    addToolbarControl(descriptor: SciToolbarControlDescriptor): this;
+    /**
+     * Adds a split control to the toolbar.
+     *
+     * A split control consists of two parts: the control and a menu button that opens a menu with related actions.
+     *
+     * The control can be any component. Data can be passed to the component via {@link SciToolbarControlDescriptor.bindings}.
+     * Because the component is not a button, it does not support a selection handler, checked state, or disabled state.
+     *
+     * To add menu items to the menu, pass a menu factory function as the second argument. The menu calls this function with a {@link SciMenuFactory} that provides methods for populating it.
+     *
+     * ```ts
+     * const matchCase = signal(false);
+     * const useRegex = signal(false);
+     *
+     * contributeMenu('toolbar:main', toolbar => toolbar
+     *   .addToolbarSplitControl({
+     *       component: FilterFieldComponent,
+     *       bindings: [inputBinding('placeholder', signal('Filter items...'))],
+     *     }, menu => menu
+     *       .addMenuItem({label: 'Match Case', checked: matchCase, onSelect: () => matchCase.update(caseSensitive => !caseSensitive)})
+     *       .addMenuItem({label: 'Regular Expressions', checked: useRegex, onSelect: () => useRegex.update(regex => !regex)}),
+     *   ),
+     * );
+     * ```
+     * ##### Allow for Separate Menu Contributions
+     *
+     * As an alternative to defining the menu items inline, assign the menu a name, allowing for separate contributions to the menu using {@link contributeMenu}.
+     *
+     * ```ts
+     * contributeMenu('toolbar:main', toolbar => toolbar
+     *   .addToolbarSplitControl({
+     *       component: FilterFieldComponent,
+     *       bindings: [inputBinding('placeholder', signal('Filter items...'))],
+     *       menu: {name: 'menu:filter-options'}, // <--- Gives the menu a name
+     *     },
+     *   ),
+     * );
+     * ```
+     *
+     * Use that name to contribute to the menu.
+     *
+     * ```ts
+     * contributeMenu('menu:filter-options', menu => menu
+     *   .addMenuItem({label: 'Match Case', checked: matchCase, onSelect: () => matchCase.update(caseSensitive => !caseSensitive)})
+     *   .addMenuItem({label: 'Regular Expressions', checked: useRegex, onSelect: () => useRegex.update(regex => !regex)}),
+     * );
+     * ```
+     *
+     * ##### Allow for Relative Positioning
+     *
+     * Assigning the split control a name allows other contributions to be positioned relative to it.
+     *
+     * ```ts
+     * contributeMenu('toolbar:main', toolbar => toolbar
+     *   .addToolbarSplitControl({
+     *       name: 'menuitem:filter', // <--- Gives the control a name
+     *       component: FilterFieldComponent,
+     *     },
+     *   ),
+     * );
+     * ```
+     *
+     * Use that name to contribute before or after the split control.
+     *
+     * ```ts
+     * contributeMenu({location: 'toolbar:main', after: 'menuitem:filter'}, toolbar => toolbar
+     *   .addToolbarButton({icon: 'save', onSelect: () => console.log('Save')}),
+     * );
+     * ```
+     *
+     * @param descriptor - Specifies the component and its inputs.
+     * @param menuFactoryFn - Optional factory function to add menu items to the split control.
+     * @returns A reference to this factory, enabling method chaining.
+     */
+    addToolbarSplitControl(descriptor: SciToolbarControlDescriptor & {
+        menu?: SciMenuDescriptor['menu'];
+    }, menuFactoryFn?: (menu: SciMenuFactory) => void): this;
+    /**
+     * Adds a group to the toolbar to group related items visually.
+     *
+     * Pass a factory function to add items to the group. The group calls this function with a {@link SciToolbarFactory} that provides methods for populating it.
+     *
+     * ```ts
+     * contributeMenu('toolbar:main', toolbar => toolbar
+     *   .addGroup(group => group
+     *     .addToolbarButton({icon: 'undo', onSelect: () => console.log('Undo')})
+     *     .addToolbarButton({icon: 'redo', onSelect: () => console.log('Redo')}),
+     *   ),
+     * );
+     * ```
+     *
+     * @param groupFactoryFn - Factory function to add items to the group.
+     * @returns A reference to this factory, enabling method chaining.
+     */
+    addGroup(groupFactoryFn: (group: SciToolbarFactory) => void): this;
+    /**
+     * Adds a group to the toolbar to group related items visually.
+     *
+     * Pass a descriptor to configure the appearance and behavior of the group.
+     * To add items to the group, pass a group factory function as the second argument. The group calls this function with a {@link SciToolbarFactory} that provides methods for populating it.
+     *
+     * ```ts
+     * contributeMenu('toolbar:main', toolbar => toolbar
+     *   .addGroup({cssClass: 'group'}, group => group
+     *     .addToolbarButton({icon: 'undo', onSelect: () => console.log('Undo')})
+     *     .addToolbarButton({icon: 'redo', onSelect: () => console.log('Redo')}),
+     *   ),
+     * );
+     * ```
+     *
+     * ##### Allow for Separate Group Contributions
+     *
+     * Assigning the group a name allows for separate contributions to the group using {@link contributeMenu}.
+     *
+     * ```ts
+     * contributeMenu('toolbar:main', toolbar => toolbar
+     *   .addGroup({name: 'toolbar:edit'}), // <--- Gives the group a name
+     * );
+     * ```
+     *
+     * Use that name to contribute to the group.
+     *
+     * ```ts
+     * contributeMenu('toolbar:edit', toolbar => toolbar
+     *   .addToolbarButton({icon: 'undo', onSelect: () => console.log('Undo')})
+     *   .addToolbarButton({icon: 'redo', onSelect: () => console.log('Redo')}),
+     * );
+     * ```
+     *
+     * ##### Allow for Relative Positioning
+     *
+     * Assigning the group a name allows other contributions to be positioned relative to it.
+     *
+     * ```ts
+     * contributeMenu('toolbar:main', toolbar => toolbar
+     *   .addGroup({
+     *       name: 'toolbar:edit', // <--- Gives the group a name
+     *     }, group => group
+     *       .addToolbarButton({icon: 'undo', onSelect: () => console.log('Undo')})
+     *       .addToolbarButton({icon: 'redo', onSelect: () => console.log('Redo')}),
+     *   ),
+     * );
+     * ```
+     *
+     * Use that name to contribute before or after the group.
+     *
+     * ```ts
+     * contributeMenu({location: 'toolbar:main', after: 'toolbar:edit'}, toolbar => toolbar
+     *   .addToolbarButton({icon: 'save', onSelect: () => console.log('Save')}),
+     * );
+     * ```
+     *
+     * @param descriptor - Configures the appearance and behavior of the group.
+     * @param groupFactoryFn - Optional factory function to add items to the group.
+     * @returns A reference to this factory, enabling method chaining.
+     */
+    addGroup(descriptor: SciToolbarGroupDescriptor, groupFactoryFn?: (group: SciToolbarFactory) => void): this;
+}
+/**
+ * Configures the appearance and behavior of a toolbar button.
+ */
+interface SciToolbarButtonDescriptor {
+    /**
+     * Specifies the name of the button, used to position other toolbar items relative to it.
+     */
+    name?: `menuitem:${string}`;
+    /**
+     * Specifies the icon to be displayed for the button.
+     *
+     * SCION uses icon providers to render icons. An icon provider can be registered using {@link provideIconProvider}.
+     *
+     * Defaults to a Material icon provider if the application has not registered an icon provider, interpreting the icon as a Material Icon font ligature.
+     * Refer to https://fonts.google.com/icons for available Material icons and instructions on including the Material icon font.
+     *
+     * For icons that can change, prefer setting the icon as a signal over tracking it manually to prevent the contribution function from re-running.
+     *
+     * A component can be used to render a custom icon. Data can be passed to the component via {@link SciComponentDescriptor.bindings}.
+     */
+    icon?: MaybeSignal<string> | ComponentType<unknown> | SciComponentDescriptor;
+    /**
+     * Specifies the label to be displayed for the button.
+     *
+     * Can be text or a translation key. A translation key starts with the percent symbol (`%`) and may include parameters in matrix notation for text interpolation.
+     *
+     * SCION uses text providers to resolve translation keys. A text provider can be registered using {@link provideTextProvider}.
+     *
+     * For texts that can change, prefer setting the text as a signal over tracking it manually to prevent the contribution function from re-running.
+     *
+     * A component can be used to render a custom label. Data can be passed to the component via {@link SciComponentDescriptor.bindings}.
+     */
+    label?: MaybeSignal<Translatable> | ComponentType<unknown> | SciComponentDescriptor;
+    /**
+     * Specifies the tooltip to be displayed when hovering over the button.
+     *
+     * Can be text or a translation key. A translation key starts with the percent symbol (`%`) and may include parameters in matrix notation for text interpolation.
+     *
+     * SCION uses text providers to resolve translation keys. A text provider can be registered using {@link provideTextProvider}.
+     *
+     * For texts that can change, prefer setting the text as a signal over tracking it manually to prevent the contribution function from re-running.
+     */
+    tooltip?: MaybeSignal<Translatable>;
+    /**
+     * Configures the button as a toggle button, with the specified checked state.
+     *
+     * Prefer setting the checked state as a signal over tracking it manually to prevent the contribution function from re-running.
+     */
+    checked?: MaybeSignal<boolean>;
+    /**
+     * Specifies the accelerator to be installed for the button.
+     *
+     * Accelerators allow for quick access using a keyboard shortcut, mapping a physical key combination (key combined with modifiers such as `Ctrl`, `Shift`, or `Alt`) to an application action.
+     */
+    accelerator?: SciKeyboardAccelerator;
+    /**
+     * Indicates whether the button is disabled. Defaults to `false`.
+     *
+     * Prefer setting the disabled state as a signal over tracking it manually to prevent the contribution function from re-running.
+     */
+    disabled?: MaybeSignal<boolean>;
+    /**
+     * Indicates whether the button is visible. Defaults to `true`.
+     *
+     * Prefer setting the visible state as a signal over tracking it manually to prevent the contribution function from re-running.
+     */
+    visible?: MaybeSignal<boolean>;
+    /**
+     * Specifies CSS classes to associate with the button.
+     */
+    cssClass?: string | string[];
+    /**
+     * Specifies HTML attributes to associate with the button.
+     *
+     * Data attributes should start with the `data-` prefix.
+     */
+    attributes?: {
+        [name: string]: string;
+    };
+    /**
+     * Specifies the handler invoked when the button is triggered by a click or keyboard shortcut.
+     *
+     * @returns A `boolean` or a Promise indicating whether to close the enclosing popover, if any. Non-checkable buttons close the popover by default.
+     */
+    onSelect: () => void | boolean | Promise<void | boolean>;
+}
+/**
+ * Configures the appearance and behavior of a toolbar menu button and its menu.
+ */
+interface SciToolbarMenuDescriptor {
+    /**
+     * Specifies the name of the menu button, used to position other toolbar items relative to it.
+     */
+    name?: `menuitem:${string}`;
+    /**
+     * Specifies the icon to be displayed for the menu button.
+     *
+     * SCION uses icon providers to render icons. An icon provider can be registered using {@link provideIconProvider}.
+     *
+     * Defaults to a Material icon provider if the application has not registered an icon provider, interpreting the icon as a Material Icon font ligature.
+     * Refer to https://fonts.google.com/icons for available Material icons and instructions on including the Material icon font.
+     *
+     * For icons that can change, prefer setting the icon as a signal over tracking it manually to prevent the contribution function from re-running.
+     *
+     * A component can be used to render a custom icon. Data can be passed to the component via {@link SciComponentDescriptor.bindings}.
+     */
+    icon?: MaybeSignal<string> | ComponentType<unknown> | SciComponentDescriptor;
+    /**
+     * Specifies the label to be displayed for the menu button.
+     *
+     * Can be text or a translation key. A translation key starts with the percent symbol (`%`) and may include parameters in matrix notation for text interpolation.
+     *
+     * SCION uses text providers to resolve translation keys. A text provider can be registered using {@link provideTextProvider}.
+     *
+     * For texts that can change, prefer setting the text as a signal over tracking it manually to prevent the contribution function from re-running.
+     *
+     * A component can be used to render a custom label. Data can be passed to the component via {@link SciComponentDescriptor.bindings}.
+     */
+    label?: MaybeSignal<Translatable> | ComponentType<unknown> | SciComponentDescriptor;
+    /**
+     * Specifies the tooltip to be displayed when hovering over the menu button.
+     *
+     * Can be text or a translation key. A translation key starts with the percent symbol (`%`) and may include parameters in matrix notation for text interpolation.
+     *
+     * SCION uses text providers to resolve translation keys. A text provider can be registered using {@link provideTextProvider}.
+     *
+     * For texts that can change, prefer setting the text as a signal over tracking it manually to prevent the contribution function from re-running.
+     */
+    tooltip?: MaybeSignal<Translatable>;
+    /**
+     * Indicates whether the menu button is disabled. Defaults to `false`.
+     *
+     * Prefer setting the disabled state as a signal over tracking it manually to prevent the contribution function from re-running.
+     */
+    disabled?: MaybeSignal<boolean>;
+    /**
+     * Indicates whether the menu button is visible. Defaults to `true`.
+     *
+     * Prefer setting the visible state as a signal over tracking it manually to prevent the contribution function from re-running.
+     */
+    visible?: MaybeSignal<boolean>;
+    /**
+     * Controls whether to display a visual indicator for the menu. Defaults to `true`.
+     *
+     * For icon menu buttons, a small triangle indicator is rendered in the bottom-right corner. For label menu buttons, a chevron is used.
+     */
+    visualMenuIndicator?: boolean;
+    /**
+     * Specifies CSS classes to associate with the menu button and menu.
+     */
+    cssClass?: string | string[];
+    /**
+     * Specifies HTML attributes to associate with the menu button and menu.
+     *
+     * Data attributes should start with the `data-` prefix.
+     */
+    attributes?: {
+        [name: string]: string;
+    };
+    /**
+     * Configures the appearance and behavior of the menu opened when clicking the menu button.
+     */
+    menu?: SciMenuDescriptor['menu'];
+}
+/**
+ * Configures the appearance and behavior of a toolbar control.
+ */
+interface SciToolbarControlDescriptor {
+    /**
+     * Specifies the name of the control, used to position other toolbar items relative to it.
+     */
+    name?: `menuitem:${string}`;
+    /**
+     * Specifies the component used to render the control.
+     */
+    component: ComponentType<unknown>;
+    /**
+     * Specifies data to pass to the component.
+     *
+     * ```ts
+     * bindings: [inputBinding('placeholder', signal('Filter items...'))];
+     * ```
+     *
+     * Inputs are available as input properties in the component.
+     *
+     * ```ts
+     * public placeholder = input.required<string>();
+     * ```
+     *
+     * @see inputBinding
+     * @see outputBinding
+     * @see twoWayBinding
+     */
+    bindings?: Binding[];
+    /**
+     * Specifies the injector used to instantiate the component, giving control over which objects are available for injection. Defaults to the element injector.
+     *
+     * ```ts
+     * Injector.create({
+     *   parent: ...,
+     *   providers: [
+     *    {provide: <TOKEN>, useValue: <VALUE>}
+     *   ],
+     * })
+     * ```
+     */
+    injector?: Injector;
+    /**
+     * Specifies providers available for injection in the component.
+     */
+    providers?: Provider[];
+    /**
+     * Specifies the tooltip to be displayed when hovering over the control.
+     *
+     * Can be text or a translation key. A translation key starts with the percent symbol (`%`) and may include parameters in matrix notation for text interpolation.
+     *
+     * SCION uses text providers to resolve translation keys. A text provider can be registered using {@link provideTextProvider}.
+     *
+     * For texts that can change, prefer setting the text as a signal over tracking it manually to prevent the contribution function from re-running.
+     */
+    tooltip?: MaybeSignal<Translatable>;
+    /**
+     * Indicates whether the control is visible. Defaults to `true`.
+     *
+     * Prefer setting the visible state as a signal over tracking it manually to prevent the contribution function from re-running.
+     */
+    visible?: MaybeSignal<boolean>;
+    /**
+     * Specifies CSS classes to associate with the control.
+     */
+    cssClass?: string | string[];
+    /**
+     * Specifies HTML attributes to associate with the control.
+     *
+     * Data attributes should start with the `data-` prefix.
+     */
+    attributes?: {
+        [name: string]: string;
+    };
+}
+/**
+ * Configures the appearance and behavior of a toolbar group.
+ */
+interface SciToolbarGroupDescriptor {
+    /**
+     * Specifies the name of the group, used to position other toolbar items relative to it.
+     */
+    name?: `toolbar:${string}`;
+    /**
+     * Indicates whether the group is disabled. Defaults to `false`.
+     *
+     * Prefer setting the disabled state as a signal over tracking it manually to prevent the contribution function from re-running.
+     */
+    disabled?: MaybeSignal<boolean>;
+    /**
+     * Indicates whether the group is visible. Defaults to `true`.
+     *
+     * Prefer setting the visible state as a signal over tracking it manually to prevent the contribution function from re-running.
+     */
+    visible?: MaybeSignal<boolean>;
+    /**
+     * Specifies CSS classes to associate with the group.
+     */
+    cssClass?: string | string[];
+}
+
+interface SciMenuFactory {
+    addMenuItem(descriptor: SciMenuItemDescriptor): this;
+    addMenu(descriptor: SciMenuDescriptor, menuFactoryFn?: (menu: SciMenuFactory) => void): this;
+    addGroup(groupFactoryFn: (group: SciMenuFactory) => void): this;
+    addGroup(descriptor: SciMenuGroupDescriptor, groupFactoryFn?: (group: SciMenuFactory) => void): this;
+}
+interface SciMenuItemDescriptor {
+    name?: `menuitem:${string}`;
+    label: MaybeSignal<Translatable> | ComponentType<unknown> | SciComponentDescriptor;
+    icon?: MaybeSignal<string> | ComponentType<unknown> | SciComponentDescriptor;
+    checked?: MaybeSignal<boolean>;
+    active?: MaybeSignal<boolean>;
+    tooltip?: MaybeSignal<Translatable>;
+    accelerator?: SciKeyboardAccelerator;
+    disabled?: MaybeSignal<boolean>;
+    visible?: MaybeSignal<boolean>;
+    actions?: (actions: SciToolbarFactory) => void;
+    onFilter?: (filter: string) => boolean;
+    cssClass?: string | string[];
+    attributes?: {
+        [name: string]: string;
+    };
+    onSelect: () => void | boolean | Promise<void | boolean>;
+}
+/**
+ * Configures a menu button and its menu.
+ */
+interface SciMenuDescriptor {
+    name?: `menuitem:${string}`;
+    label: MaybeSignal<Translatable> | ComponentType<unknown> | SciComponentDescriptor;
+    icon?: MaybeSignal<string> | ComponentType<unknown> | SciComponentDescriptor;
+    disabled?: MaybeSignal<boolean>;
+    visible?: MaybeSignal<boolean>;
+    cssClass?: string | string[];
+    attributes?: {
+        [name: string]: string;
+    };
+    /**
+     * Configures the menu.
+     */
+    menu?: {
+        name?: `menu:${string}`;
+        width?: string;
+        minWidth?: string;
+        maxWidth?: string;
+        maxHeight?: string;
+        filter?: boolean | RequireOne<SciMenuFilterConfig>;
+    };
+}
+interface SciMenuGroupDescriptor {
+    name?: `menu:${string}`;
+    label?: MaybeSignal<Translatable>;
+    collapsible?: boolean | {
+        collapsed: boolean;
+    };
+    /**
+     * TODO [menu]: Explain what glyph area is.
+     *
+     * Controls whether to hide the glyph area in this group.
+     * Defaults to displaying the glyph area if any menu item contained in the menu or its groups has an icon or is checkable.
+     */
+    glyphArea?: false;
+    disabled?: MaybeSignal<boolean>;
+    visible?: MaybeSignal<boolean>;
+    actions?: (actions: SciToolbarFactory) => void;
+    cssClass?: string | string[];
+}
+/**
+ * Features of the menu filter field.
+ */
+interface SciMenuFilterConfig<T = MaybeSignal<Translatable>> {
+    placeholder?: T;
+    notFoundMessage?: T;
+    focus?: boolean;
+}
+
+/**
+ * Opens a menu with items contributed via {@link contributeMenu}.
+ *
+ * A menu displays a list of related items in a popover, organized into groups and submenus.
+ * It closes when a menu item is selected or on an outside click. Menu items can define a keyboard accelerator for quick access.
+ *
+ * ## Menu Item Size
+ * The menu item size is based on the `--sci-menu-item-size` CSS variable and defaults to `16px`. It determines the icon size and is used to compute the font size and padding.
+ *
+ * A custom size can be defined globally using the `:root` selector:
+ *
+ * ```css
+ * sci-menu {
+ *   --sci-menu-item-size: 18px;
+ * }
+ * ```
+ *
+ * Instead of computing the font size based on `--sci-menu-item-size`, an explicit font size can be defined using the `--sci-menu-font-size` CSS variable:
+ *
+ * ```css
+ * sci-menu {
+ *   --sci-menu-item-size: 14px;
+ * }
+ * ```
+ *
+ * ## Custom Styling
+ * The appearance of the menu can be customized using the following CSS variables:
+ *
+ *  - `--sci-menu-font-size`: Font size of menu items.
+ *  - `--sci-menu-border-radius`: Border radius of a menu popover.
+ *  - `--sci-menu-min-width`: Minimum width of a menu popover.
+ *  - `--sci-menu-submenu-min-width`: Minimum width of a submenu popover.
+ *  - `--sci-menu-item-size`: Size of menu items; used as the menu item icon size and to compute font size and padding.
+ *  - `--sci-menu-item-cursor`: Cursor style when hovering over a menu item.
+ *  - `--sci-menu-item-text-color`: Text and icon color of menu items.
+ *  - `--sci-menu-item-text-color-disabled`: Text and icon color of disabled menu items.
+ *  - `--sci-menu-item-background-color-hover`: Background color of a menu item when hovered.
+ *  - `--sci-menu-item-background-color-active`: Background color of a menu item when pressed.
+ *  - `--sci-menu-item-border-radius`: Border radius of menu items.
+ *  - `--sci-menu-item-outline-width`: Outline width of menu items when focused.
+ *  - `--sci-menu-item-accelerator-text-color`: Text color of menu item accelerators.
+ *  - `--sci-menu-item-active-indicator-size`: Size of the visual indicator for active menu items.
+ *  - `--sci-menu-item-active-indicator-background-color`: Background color of the visual indicator for active menu items.
+ *  - `--sci-menu-item-active-indicator-border-radius`: Border radius of the visual indicator for active menu items.
+ *  - `--sci-menu-group-header-font-family`: Font family for group headers.
+ *  - `--sci-menu-group-header-font-size`: Font size for group headers.
+ *  - `--sci-menu-group-header-font-weight`: Font weight for group headers.
+ *  - `--sci-menu-group-header-text-color`: Text color for group headers.
+ *  - `--sci-menu-filter-outline-width`: Outline width of the filter field.
+ *  - `--sci-menu-filter-outline-radius`: Outline radius of the filter field.
+ *
+ * @experimental since 22.3.0; API and behavior may change in any version without notice.
+ */
+declare abstract class SciMenuService {
+    /**
+     * Opens a menu with items contributed to the specified menu.
+     *
+     * The menu is positioned relative to the specified anchor, vertically or horizontally. The anchor can be a coordinate, a mouse event, or a DOM element.
+     *
+     * ```ts
+     * import {inject} from '@angular/core';
+     * import {SciMenuService} from '@scion/components/menu';
+     *
+     * inject(SciMenuService).open('menu:contextmenu', { // <--- Sets the name of the menu
+     *   anchor: {x: 500, y: 600}, // <--- Sets the anchor position
+     * });
+     * ```
+     *
+     * Use the {@link contributeMenu} function to contribute to the menu by passing the menu name and a factory function.
+     * The menu calls the factory function with a {@link SciMenuFactoryFn}, providing methods for populating the menu.
+     *
+     * ```ts
+     * import {contributeMenu} from '@scion/components/menu';
+     *
+     * contributeMenu('menu:contextmenu', menu => menu
+     *   .addMenuItem({icon: 'content_copy', label: 'Copy', onSelect: () => console.log('Copy')})
+     *   .addMenuItem({icon: 'content_paste', label: 'Paste', onSelect: () => console.log('Paste')}),
+     * );
+     * ```
+     *
+     * Multiple contributions to the same menu can populate it from different places in the application. Passing a {@link SciMenuContributionLocation}
+     * gives exact control over contribution placement within the menu. By default, menu items are added in contribution order.
+     *
+     * Groups and submenus can be named to allow extension from other contributions.
+     *
+     * ## Location in the DOM
+     * By default, the menu popover is inserted after the anchor element in the DOM, or appended to the HTML body if using a coordinate anchor.
+     *
+     * A different location can be set via the {@link SciMenuOptions.viewContainerRef} option:
+     *
+     * ```ts
+     * import {inject, ViewContainerRef} from '@angular/core';
+     * import {SciMenuService} from '@scion/components/menu';
+     *
+     * inject(SciMenuService).open('menu:contextmenu', {
+     *   anchor: {x: 500, y: 600},
+     *   viewContainerRef: inject(ViewContainerRef), // <--- Sets the location in the DOM
+     * });
+     * ```
+     *
+     * ## Filterable Menu
+     * Setting the {@link SciMenuOptions.filter} option displays a filter field, enabling filtering of menu items.
+     *
+     * ```ts
+     * import {inject} from '@angular/core';
+     * import {SciMenuService} from '@scion/components/menu';
+     *
+     * inject(SciMenuService).open('menu:contextmenu', {
+     *   anchor: {x: 500, y: 600},
+     *   filter: true, // <--- Instructs the menu to display a filter field
+     * });
+     * ```
+     *
+     * ## Menu Size
+     * The menu size can be controlled via menu options. By default, a menu uses the minimum width defined by the `--sci-menu-min-width` or `--sci-menu-submenu-min-width` CSS variables.
+     *
+     * ```ts
+     * import {inject} from '@angular/core';
+     * import {SciMenuService} from '@scion/components/menu';
+     *
+     * inject(SciMenuService).open('menu:contextmenu', {
+     *   anchor: {x: 500, y: 600},
+     *   width: '500px', // <--- Sets a fixed menu width
+     *   maxHeight: '800px', // <--- Sets a maximum menu height
+     * });
+     * ```
+     *
+     * ## Context
+     * A menu can have a context, a key/value map that describes its environment. Contributions can declare a minimal required context and read the menu context.
+     *
+     * A context can be set via the {@link SciMenuOptions.context} option:
+     *
+     * ```ts
+     * import {SciMenuService} from '@scion/components/menu';
+     * import {inject} from '@angular/core';
+     *
+     * inject(SciMenuService).open('menu:contextmenu', {
+     *   anchor: {x: 500, y: 600},
+     *   context: new Map().set('key', 'value'), // <--- Sets the menu context
+     * });
+     * ```
+     *
+     * ## Accelerators
+     * Menu items can have an accelerator for quick access using a keyboard shortcut.
+     *
+     * Menu accelerators must be installed using the {@link installMenuAccelerators} function, passing the name (and context, if any) of the menu.
+     *
+     * ```ts
+     * import {installMenuAccelerators} from '@scion/components/menu';
+     *
+     * installMenuAccelerators('menu:contextmenu', {
+     *   context: new Map().set('key', 'value'), // <--- Sets the menu context
+     * });
+     * ```
+     *
+     * By default, accelerators are installed on the {@link Document}. A different accelerator target can be defined via the {@link SciMenuAcceleratorOptions.target} option.
+     *
+     * ```ts
+     * import {installMenuAccelerators} from '@scion/components/menu';
+     * import {ElementRef, inject} from '@angular/core';
+     *
+     * installMenuAccelerators('menu:contextmenu', {
+     *   target: inject(ElementRef), // <--- Sets a different accelerator target
+     * });
+     * ```
+     *
+     * Alternatively, accelerator targets can be provided at the injector level using {@link provideMenuAcceleratorTargetProvider}, for example, at the component, route, or application level,
+     * and are available to accelerators installed in the scope of this injector. Inherited targets can be overridden via {@link SciMenuAcceleratorOptions.target} option.
+     *
+     * @param name - Specifies the name of the menu. Used to look up menu items contributed via the {@link contributeMenu} function.
+     * @param options - Controls the appearance and placement of the menu. At minimum, the menu anchor must be configured to determine where to open the menu.
+     * @returns A reference to the menu, allowing to close the menu or get notified when it is closed.
+     */
+    abstract open(name: `menu:${string}`, options: SciMenuOptions): SciMenuRef;
+    /**
+     * Closes currently opened menus.
+     */
+    abstract closeAll(): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<SciMenuService, never>;
+    static ɵprov: _angular_core.ɵɵInjectableDeclaration<any>;
+}
+/**
+ * Controls the appearance and placement of a menu.
+ */
+interface SciMenuOptions {
+    /**
+     * Controls where to open the menu.
+     *
+     * Can be an HTML element or a coordinate relative to the page viewport.
+     */
+    anchor: HTMLElement | ElementRef<HTMLElement> | SciMenuOrigin | MouseEvent;
+    /**
+     * Specifies a context to describe the environment of the menu.
+     *
+     * Menu contributions may declare a required context. Only contributions matching this context are used.
+     *
+     * A context can also be provided at the injector level using {@link provideMenuContextProvider}, for example, at the component, route, or application level,
+     * and is available to menus opened in the scope of this injector. The inherited context can be overridden or extended. Setting a context entry to `undefined` clears it.
+     *
+     * ```ts
+     * import {provideMenuContextProvider} from '@scion/components/menu';
+     *
+     * providers: [
+     *   provideMenuContextProvider(() => new Map().set('key', 'value')),
+     * ];
+     * ```
+     *
+     * @see provideMenuContextProvider
+     */
+    context?: Map<string, unknown>;
+    /**
+     * Controls whether to open the menu below or to the side of the anchor.
+     */
+    align?: 'vertical' | 'horizontal';
+    /**
+     * Sets the distance (in pixels) between the menu and its anchor element along the X and Y axes.
+     *
+     * By default, the menu is aligned flush with the anchor.
+     */
+    offset?: {
+        x?: number;
+        y?: number;
+    };
+    /**
+     * Controls where to insert the menu popover into the DOM.
+     *
+     * By default, the menu popover is inserted after the anchor element, or appended to the HTML body if using a coordinate anchor.
+     */
+    viewContainerRef?: ViewContainerRef;
+    /**
+     * Specifies the preferred menu width.
+     */
+    width?: string;
+    /**
+     * Specifies the preferred minimum menu width.
+     *
+     * Defaults to the `--sci-menu-min-width` or `--sci-menu-submenu-min-width` CSS variables.
+     *
+     * If the anchor is an {@link HTMLElement}, the effective minimum width evaluates to `max(anchorWidth, minWidth)`.
+     */
+    minWidth?: string;
+    /**
+     * Specifies the maximum menu width.
+     */
+    maxWidth?: string;
+    /**
+     * Specifies the maximum menu height.
+     */
+    maxHeight?: string;
+    /**
+     * Enables users to filter menu items.
+     *
+     * Setting a descriptor allows customizing the filter field, such as defining a custom placeholder text or controlling whether the filter field is focused on open.
+     */
+    filter?: boolean | RequireOne<SciMenuFilterConfig>;
+    /**
+     * Specifies CSS classes to associate with the menu.
+     */
+    cssClass?: string | string[];
+    /**
+     * Specifies HTML attributes to associate with the menu.
+     *
+     * Data attributes should start with the `data-` prefix.
+     */
+    attributes?: {
+        [name: string]: string;
+    };
+}
+/**
+ * Coordinate relative to the top/left corner of the page viewport.
+ */
+interface SciMenuOrigin {
+    x: number;
+    y: number;
+    width?: number;
+    height?: number;
+}
+/**
+ * Represents a reference to a menu.
+ *
+ * Use to close the menu or get notified when the menu is closed.
+ */
+interface SciMenuRef {
+    /**
+     * Closes the menu. Has no effect if the menu is already closed.
+     */
+    close(): void;
+    /**
+     * Registers a callback to be notified when the menu is closed.
+     *
+     * If the menu is already closed, the callback is executed immediately.
+     */
+    onClose: (fn: () => void) => void;
+}
+
+/**
+ * // TODO [menu] documentation
+ *
+ * @docs-private Not public API. Used by frameworks integrating the SCION Menu API. Applications should not use this service.
+ */
+declare class ɵSciMenuService implements SciMenuService {
+    private readonly _menuRegistry;
+    private readonly _environmentContext;
+    /** @inheritDoc */
+    open(menu: `menu:${string}` | SciMenuItemLike[], options: SciMenuOptions): SciMenuRef;
+    /** @inheritDoc */
+    closeAll(): void;
+    /**
+     * The function:
+     * - Must be called within an injection context, or an explicit {@link Injector} passed.
+     * - Must be called in a non-reactive (non-tracking) context.
+     *
+     * @docs-private Not public API. Used by frameworks integrating the SCION Menu API. Applications should not use this method.
+     */
+    menuItems(location: MaybeSignal<`menu:${string}` | `toolbar:${string}` | `menubar:${string}`>, context: MaybeSignal<Map<string, unknown>>, options?: {
+        injector?: Injector;
+        metadata?: {
+            [key: string]: unknown;
+        };
+    }): Signal<SciMenuItemLike[]>;
+    /** @docs-private Not public API. Used by frameworks integrating the SCION Menu API. Applications should not use this method. */
+    menuContributions(location: MaybeSignal<`menu:${string}` | `toolbar:${string}` | `menubar:${string}`>, context: MaybeSignal<Map<string, unknown>>, options?: {
+        injector?: Injector;
+        metadata?: {
+            [key: string]: unknown;
+        };
+    }): Signal<SciMenuContribution[]>;
+    /** @docs-private Not public API. Used by frameworks integrating the SCION Menu API. Applications should not use this method. */
+    contributeMenu(location: SciMenuContributionLocationLike, factoryFn: SciMenuFactoryFnLike, options?: SciMenuContributionOptions): Disposable;
+    /**
+     * Gets installed keyboard accelerators for menu items that match the given context.
+     *
+     * A match does not require an identical context. All common context keys must have identical context values.
+     *
+     * Inherits the context from the current injector hierarchy, but can be overridden via `context` options. See {@link provideMenuContextProvider}.
+     *
+     * @docs-private Not public API. Used by frameworks integrating the SCION Menu API. Applications should not use this method.
+     */
+    accelerators(options?: {
+        context?: MaybeSignal<Map<string, unknown>>;
+    }): Signal<SciKeyboardAccelerator[]>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ɵSciMenuService, never>;
+    static ɵprov: _angular_core.ɵɵInjectableDeclaration<any>;
+}
+
+/**
+ * Enables integrators to intercept the registration and retrieval of menu contributions and to control where menu popovers open.
+ *
+ * Adapters can handle or augment calls. Multiple adapters form a chain and are called one by one in registration order.
+ *
+ * Calling 'next' passes the call to the next adapter, or to the registry if it is the last adapter in the chain.
+ *
+ * TODO [menu] documentation
+ *
+ * @experimental since 22.3.0; API and behavior may change in any version without notice.
+ */
+declare abstract class SciMenuAdapter {
+    abstract contributeMenu?(location: SciMenuContributionLocationLike, factoryFn: SciMenuFactoryFnLike, options: SciMenuContributionOptions, next: SciMenuAdapterChain): Disposable;
+    abstract menuContributions?(location: Signal<`menu:${string}` | `toolbar:${string}` | `menubar:${string}`>, context: Signal<Map<string, unknown>>, options: {
+        injector?: Injector;
+        metadata?: {
+            [key: string]: unknown;
+        };
+    }, next: SciMenuAdapterChain): Signal<SciMenuContribution[]>;
+    abstract menuItems?(location: Signal<`menu:${string}` | `toolbar:${string}` | `menubar:${string}`>, context: Signal<Map<string, unknown>>, options: {
+        injector?: Injector;
+        metadata?: {
+            [key: string]: unknown;
+        };
+    }, next: SciMenuAdapterChain): Signal<SciMenuItemLike[]>;
+    abstract openMenu?(menu: `menu:${string}` | SciMenuItemLike[], options: SciMenuOptions, next: SciMenuAdapterChain): SciMenuRef;
+    abstract closeMenus?(next: SciMenuAdapterChain): void;
+    abstract accelerators?(context: Signal<Map<string, unknown>>, next: SciMenuAdapterChain): Signal<SciKeyboardAccelerator[]>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<SciMenuAdapter, never>;
+    static ɵprov: _angular_core.ɵɵInjectableDeclaration<any>;
+}
+/**
+ * Represents the next adapter in the adapter chain.
+ */
+interface SciMenuAdapterChain {
+    contributeMenu(location: SciMenuContributionLocationLike, factoryFn: SciMenuFactoryFnLike, options: SciMenuContributionOptions): Disposable;
+    menuContributions(location: Signal<`menu:${string}` | `toolbar:${string}` | `menubar:${string}`>, context: Signal<Map<string, unknown>>, options: {
+        injector?: Injector;
+        metadata?: {
+            [key: string]: unknown;
+        };
+    }): Signal<SciMenuContribution[]>;
+    menuItems(location: Signal<`menu:${string}` | `toolbar:${string}` | `menubar:${string}`>, context: Signal<Map<string, unknown>>, options: {
+        injector?: Injector;
+        metadata?: {
+            [key: string]: unknown;
+        };
+    }): Signal<SciMenuItemLike[]>;
+    openMenu(menu: `menu:${string}` | SciMenuItemLike[], options: SciMenuOptions): SciMenuRef;
+    closeMenus(): void;
+    accelerators(context: Signal<Map<string, unknown>>): Signal<SciKeyboardAccelerator[]>;
+}
+
+/**
+ * Contributes tools to a {@link SciToolbarComponent} with the given name.
+ *
+ * A toolbar is a horizontal or vertical container that provides quick access to context-related tools. It can contain buttons, toggles, menus, and other controls,
+ * with related items grouped together.
+ *
+ * The toolbar calls the passed factory function with a {@link SciToolbarFactory}. The factory provides methods for populating the toolbar.
+ * The factory function runs in a reactive context, running again when tracked signals change. It can call `inject` to get required dependencies.
+ *
+ * ```ts
+ * contributeMenu('toolbar:main', (toolbar, context) => toolbar
+ *   .addToolbarButton({icon: 'undo', accelerator: {ctrl: true, key: 'Z'}, tooltip: 'Undo', onSelect: () => console.log('Undo')})
+ *   .addToolbarButton({icon: 'redo', accelerator: {ctrl: true, key: 'Y'}, tooltip: 'Redo', onSelect: () => console.log('Redo')})
+ *   .addGroup(group => group
+ *     .addToolbarButton({icon: 'content_copy', accelerator: {ctrl: true, key: 'C'}, tooltip: 'Copy', onSelect: () => console.log('Copy')})
+ *     .addToolbarButton({icon: 'content_paste', accelerator: {ctrl: true, key: 'V'}, tooltip: 'Paste', onSelect: () => console.log('Paste')}),
+ *   )
+ *   .addToolbarMenu({icon: 'folder', tooltip: 'File'}, menu => menu
+ *     .addMenuItem({icon: 'save', label: 'Save', accelerator: {ctrl: true, key: 'S'}, onSelect: () => console.log('Save')})
+ *     .addMenuItem({icon: 'print', label: 'Print', accelerator: {ctrl: true, key: 'P'}, onSelect: () => console.log('Print')})
+ *     .addMenu({icon: 'file_download', label: 'Export As...'}, menu => menu
+ *       .addMenuItem({icon: 'picture_as_pdf', label: 'PDF Document', onSelect: () => console.log('PDF Document')})
+ *       .addMenuItem({icon: 'table_view', label: 'Excel Spreadsheet', onSelect: () => console.log('Excel Spreadsheet')}),
+ *     ),
+ *   ),
+ * );
+ * ```
+ *
+ * A toolbar can have a context, a key/value map that describes its environment. The contribution can declare a minimal required context via {@link SciMenuContributionOptions.requiredContext}.
+ * The toolbar context is passed as the second argument to the factory function.
+ *
+ * Multiple contributions to the same toolbar can populate it from different places in the application. Passing a {@link SciToolbarContributionLocation}
+ * gives exact control over contribution placement within the toolbar. By default, toolbar items are added in contribution order.
+ *
+ * Menus and groups can be named to allow extension from other contributions.
+ *
+ * This function must be called within an injection context, or an explicit {@link Injector} passed. The contribution is disposed when the injection context or the passed injector is destroyed.
+ *
+ * @experimental since 22.3.0; API and behavior may change in any version without notice.
+ *
+ * @param location - Identifies the toolbar to contribute to. Passing a {@link SciToolbarContributionLocation} gives exact control over placement.
+ * @param toolbarFactoryFn - Specifies the function to contribute tools to the toolbar. The function is called in a reactive context and can call `inject` to get required dependencies.
+ * @param options - Controls contribution to the toolbar, for example, the minimal required context.
+ * @returns A handle that can be used to manually dispose the contribution. The contribution is disposed automatically when the calling (or passed) injection context is destroyed.
+ */
+declare function contributeMenu(location: `toolbar:${string}` | SciToolbarContributionLocation, toolbarFactoryFn: SciToolbarFactoryFn, options?: SciMenuContributionOptions): Disposable;
+/**
+ * Contributes menus to a {@link SciMenubarComponent} with the given name.
+ *
+ * A menubar displays a horizontal row of menus, typically placed at the top of the application.
+ *
+ * The menubar calls the passed factory function with a {@link SciMenubarFactory}. The factory provides methods for populating the menubar.
+ * The factory function runs in a reactive context, running again when tracked signals change. It can call `inject` to get required dependencies.
+ *
+ * TODO [menu] Add example
+ *
+ * A menubar can have a context, a key/value map that describes its environment. The contribution can declare a minimal required context via {@link SciMenuContributionOptions.requiredContext}.
+ * The menubar context is passed as the second argument to the factory function.
+ *
+ * Multiple contributions to the same menubar can populate it from different places in the application. Passing a {@link SciMenubarContributionLocation}
+ * gives exact control over contribution placement within the menubar. By default, menus are added in contribution order.
+ *
+ * Menus and groups can be named to allow extension from other contributions.
+ *
+ * This function must be called within an injection context, or an explicit {@link Injector} passed. The contribution is disposed when the injection context or the passed injector is destroyed.
+ *
+ * @experimental since 22.3.0; API and behavior may change in any version without notice.
+ *
+ * @param location - Identifies the menubar to contribute to. Passing a {@link SciMenubarContributionLocation} gives exact control over placement.
+ * @param menubarFactoryFn - Specifies the function to contribute menus to the menubar. The function is called in a reactive context and can call `inject` to get required dependencies.
+ * @param options - Controls contribution to the menubar, for example, the minimal required context.
+ * @returns A handle that can be used to manually dispose the contribution. The contribution is disposed automatically when the calling (or passed) injection context is destroyed.
+ */
+declare function contributeMenu(location: `menubar:${string}` | SciMenubarContributionLocation, menubarFactoryFn: SciMenubarFactoryFn, options?: SciMenuContributionOptions): Disposable;
+/**
+ * Contributes menu items to a menu with the given name.
+ *
+ * A menu displays a list of related items in a popover, organized into groups and submenus.
+ * It closes when a menu item is selected or on an outside click. Menu items can define a keyboard accelerator for quick access.
+ *
+ * The menu calls the passed factory function with a {@link SciMenuFactory}. The factory provides methods for populating the menu.
+ * The factory function runs in a reactive context, running again when tracked signals change. It can call `inject` to get required dependencies.
+ *
+ * TODO [menu] Add example
+ *
+ * A menu can have a context, a key/value map that describes its environment. The contribution can declare a minimal required context via {@link SciMenuContributionOptions.requiredContext}.
+ * The menu context is passed as the second argument to the factory function.
+ *
+ * Multiple contributions to the same menu can populate it from different places in the application. Passing a {@link SciMenuContributionLocation}
+ * gives exact control over contribution placement within the menu. By default, menu items are added in contribution order.
+ *
+ * Menus and groups can be named to allow extension from other contributions.
+ *
+ * This function must be called within an injection context, or an explicit {@link Injector} passed. The contribution is disposed when the injection context or the passed injector is destroyed.
+ *
+ * @experimental since 22.3.0; API and behavior may change in any version without notice.
+ *
+ * @param location - Identifies the menu to contribute to. Passing a {@link SciMenuContributionLocation} gives exact control over placement.
+ * @param menuFactoryFn - Specifies the function to contribute menu items to the menu. The function is called in a reactive context and can call `inject` to get required dependencies.
+ * @param options - Controls contribution to the menu, for example, the minimal required context.
+ * @returns A handle that can be used to manually dispose the contribution. The contribution is disposed automatically when the calling (or passed) injection context is destroyed.
+ */
+declare function contributeMenu(location: `menu:${string}` | SciMenuContributionLocation, menuFactoryFn: SciMenuFactoryFn, options?: SciMenuContributionOptions): Disposable;
+
+/**
+ * Displays items contributed via the {@link contributeMenu} function matching the toolbar's name.
+ *
+ * A toolbar is a horizontal or vertical container providing quick access to context-related tools.
+ * It contains buttons, toggles, menus, and other controls, with related items grouped together.
+ *
+ * The toolbar must be assigned a name, used as the location when contributing to the toolbar.
+ * The name must start with the `toolbar:` prefix.
+ *
+ * ```html
+ * <sci-toolbar name="toolbar:main"/>
+ * ```
+ *
+ * Use the {@link contributeMenu} function to contribute to the toolbar by passing the toolbar name and a factory function.
+ * The toolbar calls the factory function with a {@link SciToolbarFactory}, providing methods for populating the toolbar.
+ *
+ * ```ts
+ * import {contributeMenu} from '@scion/components/menu';
+ *
+ * contributeMenu('toolbar:main', toolbar => toolbar
+ *   .addToolbarButton({icon: 'undo', accelerator: {ctrl: true, key: 'Z'}, tooltip: 'Undo', onSelect: () => console.log('Undo')})
+ *   .addToolbarButton({icon: 'redo', accelerator: {ctrl: true, key: 'Y'}, tooltip: 'Redo', onSelect: () => console.log('Redo')})
+ *   .addGroup(group => group
+ *     .addToolbarButton({icon: 'content_copy', accelerator: {ctrl: true, key: 'C'}, tooltip: 'Copy', onSelect: () => console.log('Copy')})
+ *     .addToolbarButton({icon: 'content_paste', accelerator: {ctrl: true, key: 'V'}, tooltip: 'Paste', onSelect: () => console.log('Paste')}),
+ *   )
+ *   .addToolbarMenu({icon: 'folder', tooltip: 'File'}, menu => menu
+ *     .addMenuItem({icon: 'save', label: 'Save', accelerator: {ctrl: true, key: 'S'}, onSelect: () => console.log('Save')})
+ *     .addMenuItem({icon: 'print', label: 'Print', accelerator: {ctrl: true, key: 'P'}, onSelect: () => console.log('Print')})
+ *     .addMenu({icon: 'file_download', label: 'Export As...'}, menu => menu
+ *       .addMenuItem({icon: 'picture_as_pdf', label: 'PDF Document', onSelect: () => console.log('PDF Document')})
+ *       .addMenuItem({icon: 'table_view', label: 'Excel Spreadsheet', onSelect: () => console.log('Excel Spreadsheet')}),
+ *     ),
+ *   ),
+ * );
+ * ```
+ *
+ * Multiple contributions to the same toolbar can populate it from different places in the application. Passing a {@link SciToolbarContributionLocation}
+ * gives exact control over contribution placement within the toolbar. By default, toolbar items are added in contribution order.
+ *
+ * Menus and groups can be named to allow extension from other contributions.
+ *
+ * ## Context
+ * A toolbar can have a context, a key/value map that describes its environment. Contributions can declare a minimal required context and read the toolbar context.
+ *
+ * A context can be set on the toolbar with the `context` input:
+ *
+ * ```html
+ * <sci-toolbar name="toolbar:main" [context]="..."/>
+ * ```
+ *
+ * ## Accelerator Target
+ * Tools can have an accelerator for quick access using a keyboard shortcut. By default, the toolbar uses the {@link Document} as the accelerator target.
+ *
+ * The accelerator target can be changed via the `acceleratorTarget` input:
+ *
+ * ```html
+ * <sci-toolbar name="toolbar:main" [acceleratorTarget]="..."/>
+ * ```
+ *
+ * ## Toolbar Size
+ * The toolbar size is based on the `--sci-toolbar-item-size` CSS variable and defaults to 16px. It determines the icon size and is used to compute the font size and padding.
+ *
+ * A custom size can be defined globally using the `:root` selector or scoped to a specific toolbar.
+ *
+ * ```css
+ * sci-toolbar {
+ *   --sci-toolbar-item-size: 18px;
+ * }
+ * ```
+ *
+ * Instead of computing the font size based on `--sci-toolbar-item-size`, an explicit font size can be defined using the `--sci-toolbar-font-size` CSS variable, either globally or at the toolbar level.
+ *
+ * ```css
+ * sci-toolbar {
+ *   --sci-toolbar-font-size: 14px;
+ * }
+ * ```
+ *
+ * ## Hiding an Empty Toolbar
+ * If the toolbar has no tools, it can be hidden using the CSS `:empty` pseudo-class:
+ *
+ * ```css
+ * sci-toolbar:empty {
+ *   display: none;
+ * }
+ * ```
+ *
+ * ## Custom Styling
+ * The appearance of the toolbar can be customized using the following CSS variables, either globally in the `:root` or on the toolbar level.
+ *
+ * - `--sci-toolbar-font-size`: Font size of toolbar items.
+ * - `--sci-toolbar-item-size`: Size of toolbar items; used as the toolbar item icon size and to compute font size and padding.
+ * - `--sci-toolbar-item-cursor`: Cursor style when hovering over a toolbar item.
+ * - `--sci-toolbar-item-text-color`: Text and icon color of toolbar items.
+ * - `--sci-toolbar-item-text-color-disabled`: Text and icon color of disabled toolbar items.
+ * - `--sci-toolbar-item-background-color`: Background color of toolbar items.
+ * - `--sci-toolbar-item-background-color-hover`: Background color of a toolbar item when hovered.
+ * - `--sci-toolbar-item-background-color-active`: Background color of a toolbar item when pressed.
+ * - `--sci-toolbar-item-background-color-checked`: Background color of toggled toolbar items.
+ * - `--sci-toolbar-item-border-radius`: Border radius of toolbar items.
+ * - `--sci-toolbar-item-border-color-hover`: Border color of toolbar items when hovered.
+ * - `--sci-toolbar-item-border-color-checked`: Border color of toggled toolbar items.
+ * - `--sci-toolbar-item-outline-width`: Outline width of toolbar items when focused.
+ * - `--sci-toolbar-item-menu-indicator-color`: Color of the menu indicator for toolbar items without a label.
+ * - `--sci-toolbar-item-menu-indicator-color-disabled`: Color of the menu indicator if disabled.
+ * - `--sci-toolbar-item-menu-indicator-size`: Size of the menu indicator.
+ *
+ * @experimental since 22.3.0; API and behavior may change in any version without notice.
+ */
+declare class SciToolbarComponent {
+    /**
+     * Defines the name of the toolbar. The name must start with the `toolbar:` prefix.
+     *
+     * Use this name to contribute tools to the toolbar using the {@link contributeMenu} function.
+     */
+    readonly name: _angular_core.InputSignal<`toolbar:${string}`>;
+    /**
+     * Specifies the orientation of the toolbar. Defaults to `horizontal`.
+     */
+    readonly orientation: _angular_core.InputSignal<"horizontal" | "vertical">;
+    /**
+     * Specifies a context to describe the environment of the toolbar.
+     *
+     * Toolbar contributions may declare a required context. Only contributions matching this context are used.
+     *
+     * A context can also be provided at the injector level using {@link provideMenuContextProvider}, for example, at the component, route, or application level,
+     * and is available to toolbars used in the scope of this injector. The inherited context can be overridden or extended. Setting a context entry to `undefined` clears it.
+     *
+     * ```ts
+     * import {provideMenuContextProvider} from '@scion/components/menu';
+     *
+     * providers: [
+     *   provideMenuContextProvider(() => new Map().set('key', 'value')),
+     * ];
+     * ```
+     *
+     * @see provideMenuContextProvider
+     */
+    readonly context: _angular_core.InputSignal<Map<string, unknown> | undefined>;
+    /**
+     * Specifies the accelerator targets for the toolbar. Defaults to {@link Document}.
+     *
+     * Alternatively, accelerator targets can be provided at the injector level using {@link provideMenuAcceleratorTargetProvider}, for example, at the component, route, or application level,
+     * and are available to toolbars used in the scope of this injector. Inherited targets can be overridden.
+     *
+     * ```ts
+     * import {provideMenuAcceleratorTargetProvider} from '@scion/components/menu';
+     * import {ElementRef, inject} from '@angular/core';
+     *
+     * providers: [
+     *   provideMenuAcceleratorTargetProvider(() => inject(ElementRef)),
+     * ];
+     * ```
+     */
+    readonly acceleratorTarget: _angular_core.InputSignal<MaybeArray<Element | ElementRef<Element>> | undefined>;
+    /**
+     * Controls where to attach menu popovers in the DOM. By default, popovers are added as a direct sibling of the toolbar.
+     */
+    readonly popoverViewContainerRef: _angular_core.InputSignal<ViewContainerRef>;
+    /**
+     * Indicates whether any menu within the toolbar is currently open.
+     *
+     * TODO [dwi][API] How to name that metod? Cannot be internal because used by table.
+     */
+    readonly menuOpen: _angular_core.Signal<boolean>;
+    private readonly _environmentContext;
+    private readonly _context;
+    private readonly _virtualToolbarGroupComponent;
+    protected readonly menuItems: _angular_core.Signal<_scion_components_menu.SciMenuItemLike[]>;
+    constructor();
+    /**
+     * Creates and attaches a {@link SciToolbarGroupComponent} using this component as host,
+     * rendering top-level toolbar items and groups as direct children inside `<sci-toolbar/>`.
+     */
+    private attachVirtualToolbarGroup;
+    /**
+     * Installs accelerators of menu items in this toolbar, recursively for menu items in submenus and groups.
+     */
+    private installAccelerators;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<SciToolbarComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<SciToolbarComponent, "sci-toolbar", never, { "name": { "alias": "name"; "required": true; "isSignal": true; }; "orientation": { "alias": "orientation"; "required": false; "isSignal": true; }; "context": { "alias": "context"; "required": false; "isSignal": true; }; "acceleratorTarget": { "alias": "acceleratorTarget"; "required": false; "isSignal": true; }; "popoverViewContainerRef": { "alias": "popoverViewContainerRef"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+/**
+ * TODO [menu]: Explain how to size the menubar. (height can be set)
+ *
+ * @experimental since 22.3.0; API and behavior may change in any version without notice.
+ */
+declare class SciMenubarComponent {
+    readonly name: _angular_core.InputSignal<`menubar:${string}`>;
+    readonly context: _angular_core.InputSignal<Map<string, unknown> | undefined>;
+    readonly acceleratorTarget: _angular_core.InputSignal<MaybeArray<Element | ElementRef<Element>> | undefined>;
+    readonly viewContainerRef: _angular_core.InputSignal<ViewContainerRef>;
+    private readonly _environmentContext;
+    private readonly _context;
+    protected readonly menuItems: Signal<SciMenuItem[]>;
+    protected readonly activeMenuItem: _angular_core.WritableSignal<{
+        menuItem: SciMenuItem;
+        element: HTMLElement;
+        closing?: true | "prevented";
+    } | null>;
+    constructor();
+    /**
+     * Method invoked when clicking on a menu item.
+     */
+    protected onMenuItemClick(menuItem: SciMenuItem, element: HTMLElement): void;
+    /**
+     * Method invoked before clicking on a menu item.
+     *
+     * When clicking on the active menu item, mark it as closing to prevent immediate re-opening race condition on subsequent click event.
+     */
+    protected onMenuItemMouseDown(menuItem: SciMenuItem): void;
+    /**
+     * Method invoked when moving the pointer over a menu item.
+     */
+    protected onMenuItemMouseEnter(menuItem: SciMenuItem, element: HTMLElement): void;
+    /**
+     * Method invoked when moving the pointer out of a menu item.
+     */
+    protected onMenuItemMouseLeave(menuItem: SciMenuItem): void;
+    /**
+     * Opens a menu based on {@link activeMenuItem}.
+     */
+    private installMenuOpener;
+    /**
+     * Installs accelerators of menu items in this menubar, recursively for menu items in submenus and groups.
+     */
+    private installAccelerators;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<SciMenubarComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<SciMenubarComponent, "sci-menubar", never, { "name": { "alias": "name"; "required": true; "isSignal": true; }; "context": { "alias": "context"; "required": false; "isSignal": true; }; "acceleratorTarget": { "alias": "acceleratorTarget"; "required": false; "isSignal": true; }; "viewContainerRef": { "alias": "viewContainerRef"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+/**
+ * Registers a {@link SciMenuContextProviderFn} to provide context to menu locations and contributions.
+ *
+ * Provided context is applied to menu locations and contributions in the scope of the injector providing this function.
+ * Individual locations and contributions can extend or override the provided context.
+ *
+ * Multiple providers can be registered. Providers at different injector tree levels form a hierarchy.
+ *
+ * @see SciMenuContextProviderFn
+ */
+declare function provideMenuContextProvider(providerFn: SciMenuContextProviderFn): Provider[];
+/**
+ * Registers a {@link SciMenuInjectionContextProviderFn} to provide dependency injection tokens for a given menu context.
+ *
+ * Provided tokens are available for dependency injection for contributions registered in the scope of the injector providing this function.
+ * Tokens can be injected in the factory passed to {@link contributeMenu}.
+ *
+ * Multiple providers can be registered. Providers at different injector tree levels form a hierarchy.
+ *
+ * @see SciMenuInjectionContextProviderFn
+ */
+declare function provideMenuInjectionContextProvider(providerFn: SciMenuInjectionContextProviderFn): Provider[];
+/**
+ * Registers a {@link SciMenuAcceleratorTargetProviderFn} to provide accelerator targets to menu locations.
+ *
+ * Provided accelerator targets are available to menu locations in the scope of the injector providing this function.
+ * Individual locations can override the provided targets.
+ *
+ * Multiple providers can be registered. Providers at different injector tree levels form a hierarchy.
+ *
+ * @see SciMenuAcceleratorTargetProviderFn
+ */
+declare function provideMenuAcceleratorTargetProvider(providerFn: SciMenuAcceleratorTargetProviderFn): Provider[];
+/**
+ * Signature of a function to provide context to menu locations and contributions.
+ *
+ * A menu location is a toolbar, menubar, or menu. A location or contribution can have a context (`Map`)
+ * describing its environment. A contribution is eligible for a location only if the location's context fully
+ * contains the contribution's context.
+ *
+ * Register this provider using the {@link provideMenuContextProvider} function.
+ *
+ * The function can call `inject` to get dependencies from the injector providing this function.
+ *
+ * @param callingInjector - Use to inject dependencies from the injector calling this function, e.g., the injector of the menu location.
+ */
+type SciMenuContextProviderFn = (callingInjector: Injector) => MaybeSignal<Map<string, unknown> | undefined>;
+/**
+ * Signature of a function to provide dependency injection tokens for a given menu context.
+ *
+ * The passed menu context is the context of a menu location (toolbar, menubar, or menu) describing its environment.
+ * Returned tokens are available for dependency injection in the menu factory passed to {@link contributeMenu}.
+ *
+ * Register this provider using the {@link provideMenuInjectionContextProvider} function.
+ *
+ * The function can call `inject` to get any required dependencies.
+ */
+type SciMenuInjectionContextProviderFn = (context: Map<string, unknown>) => Provider[];
+/**
+ * Signature of a function to provide accelerator targets to menu locations.
+ *
+ * An accelerator target is a DOM element on which a menu location (toolbar, menubar, or menu) listens
+ * for keyboard events for accelerators configured on menu items.
+ *
+ * Register this provider using the {@link provideMenuAcceleratorTargetProvider} function.
+ *
+ * The function can call `inject` to get dependencies from the injector providing this function.
+ *
+ * @param callingInjector - Use to inject dependencies from the injector calling this function, e.g., the injector of the menu location.
+ */
+type SciMenuAcceleratorTargetProviderFn = (callingInjector: Injector) => MaybeSignal<MaybeArray<Element | ElementRef<Element>> | undefined>;
+
+/**
+ * Injects dependency injection providers of the given menu context based on the current injection context.
+ *
+ * Must be called within an injection context, or an explicit {@link Injector} passed.
+ *
+ * @see provideMenuInjectionContextProvider
+ * @docs-private Not public API. Used by frameworks integrating the SCION Menu API. Applications should not use this function.
+ */
+declare function injectMenuInjectionContextProviders(menuContext: Map<string, unknown>, options?: {
+    injector?: Injector;
+}): Provider[];
+
+export { SciMenuAdapter, SciMenuService, SciMenubarComponent, SciToolbarComponent, contributeMenu, installMenuAccelerators, provideMenuAcceleratorTargetProvider, provideMenuContextProvider, provideMenuInjectionContextProvider, ɵSciMenuService, injectMenuInjectionContextProviders as ɵinjectMenuInjectionContextProviders };
+export type { SciKeyboardAccelerator, SciMenuAcceleratorOptions, SciMenuAcceleratorTargetProviderFn, SciMenuAdapterChain, SciMenuContextProviderFn, SciMenuContribution, SciMenuContributionLocation, SciMenuContributionLocationLike, SciMenuContributionOptions, SciMenuContributionPosition, SciMenuContributionPositionLike, SciMenuDescriptor, SciMenuFactory, SciMenuFactoryFn, SciMenuFactoryFnLike, SciMenuFilterConfig, SciMenuGroup, SciMenuGroupDescriptor, SciMenuInjectionContextProviderFn, SciMenuItem, SciMenuItemDescriptor, SciMenuItemLike, SciMenuOptions, SciMenuOrigin, SciMenuRef, SciMenubarContributionLocation, SciMenubarContributionPosition, SciMenubarFactory, SciMenubarFactoryFn, SciMenubarMenuDescriptor, SciToolbarButtonDescriptor, SciToolbarContributionLocation, SciToolbarContributionPosition, SciToolbarControlDescriptor, SciToolbarFactory, SciToolbarFactoryFn, SciToolbarGroupDescriptor, SciToolbarMenuDescriptor };