/**
 * @license Copyright (c) 2003-2026, CKSource Holding sp. z o.o. All rights reserved.
 * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-licensing-options
 */
/**
 * @module ui/dropdown/dropdownview
 */
import { View } from '../view.js';
import type { DropdownButton } from './button/dropdownbutton.js';
import type { DropdownPanelView, PanelPosition } from './dropdownpanelview.js';
import type { FocusableView } from '../focuscycler.js';
import { type ListView } from '../list/listview.js';
import { type ToolbarView } from '../toolbar/toolbarview.js';
import { type DropdownMenuRootListView } from './menu/dropdownmenurootlistview.js';
import { KeystrokeHandler, FocusTracker, type Locale, type PositioningFunction } from '@ckeditor/ckeditor5-utils';
import '../../theme/components/dropdown/dropdown.css';
/**
 * The dropdown view class. It manages the dropdown button and dropdown panel.
 *
 * In most cases, the easiest way to create a dropdown is by using the {@link module:ui/dropdown/utils~createDropdown}
 * util:
 *
 * ```ts
 * const dropdown = createDropdown( locale );
 *
 * // Configure dropdown's button properties:
 * dropdown.buttonView.set( {
 * 	label: 'A dropdown',
 * 	withText: true
 * } );
 *
 * dropdown.render();
 *
 * dropdown.panelView.element.textContent = 'Content of the panel';
 *
 * // Will render a dropdown with a panel containing a "Content of the panel" text.
 * document.body.appendChild( dropdown.element );
 * ```
 *
 * If you want to add a richer content to the dropdown panel, you can use the {@link module:ui/dropdown/utils~addListToDropdown}
 * and {@link module:ui/dropdown/utils~addToolbarToDropdown} helpers. See more examples in
 * {@link module:ui/dropdown/utils~createDropdown} documentation.
 *
 * If you want to create a completely custom dropdown, then you can compose it manually:
 *
 * ```ts
 * const button = new DropdownButtonView( locale );
 * const panel = new DropdownPanelView( locale );
 * const dropdown = new DropdownView( locale, button, panel );
 *
 * button.set( {
 * 	label: 'A dropdown',
 * 	withText: true
 * } );
 *
 * dropdown.render();
 *
 * panel.element.textContent = 'Content of the panel';
 *
 * // Will render a dropdown with a panel containing a "Content of the panel" text.
 * document.body.appendChild( dropdown.element );
 * ```
 *
 * However, dropdown created this way will contain little behavior. You will need to implement handlers for actions
 * such as {@link module:ui/bindings/clickoutsidehandler~clickOutsideHandler clicking outside an open dropdown}
 * (which should close it) and support for arrow keys inside the panel. Therefore, unless you really know what
 * you do and you really need to do it, it is recommended to use the {@link module:ui/dropdown/utils~createDropdown} helper.
 */
export declare class DropdownView extends View<HTMLDivElement> {
    /**
     * Button of the dropdown view. Clicking the button opens the {@link #panelView}.
     */
    readonly buttonView: DropdownButton & FocusableView;
    /**
     * Panel of the dropdown. It opens when the {@link #buttonView} is
     * {@link module:ui/button/button~Button#event:execute executed} (i.e. clicked).
     *
     * Child views can be added to the panel's `children` collection:
     *
     * ```ts
     * dropdown.panelView.children.add( childView );
     * ```
     *
     * See {@link module:ui/dropdown/dropdownpanelview~DropdownPanelView#children} and
     * {@link module:ui/viewcollection~ViewCollection#add}.
     */
    readonly panelView: DropdownPanelView;
    /**
     * Tracks information about the DOM focus in the dropdown.
     */
    readonly focusTracker: FocusTracker;
    /**
     * Instance of the {@link module:utils/keystrokehandler~KeystrokeHandler}. It manages
     * keystrokes of the dropdown:
     *
     * * <kbd>▼</kbd> opens the dropdown,
     * * <kbd>◀</kbd> and <kbd>Esc</kbd> closes the dropdown.
     */
    readonly keystrokes: KeystrokeHandler;
    /**
     * A child {@link module:ui/list/listview~ListView list view} of the dropdown located
     * in its {@link module:ui/dropdown/dropdownview~DropdownView#panelView panel}.
     *
     * **Note**: Only supported when dropdown has list view added using {@link module:ui/dropdown/utils~addListToDropdown}.
     */
    listView?: ListView;
    /**
     * A child toolbar of the dropdown located in the
     * {@link module:ui/dropdown/dropdownview~DropdownView#panelView panel}.
     *
     * **Note**: Only supported when dropdown has a toolbar added using {@link module:ui/dropdown/utils~addToolbarToDropdown}.
     */
    toolbarView?: ToolbarView;
    /**
     * A child menu component of the dropdown located
     * in its {@link module:ui/dropdown/dropdownview~DropdownView#panelView panel}.
     *
     * **Note**: Only supported when dropdown has a menu added using {@link module:ui/dropdown/utils~addMenuToDropdown}.
     */
    menuView?: DropdownMenuRootListView;
    /**
     * Controls whether the dropdown view is open, i.e. shows or hides the {@link #panelView panel}.
     *
     * **Note**: When the dropdown gets open, it will attempt to call `focus()` on the first child of its {@link #panelView}.
     * See {@link module:ui/dropdown/utils~addToolbarToDropdown}, {@link module:ui/dropdown/utils~addListToDropdown}, and
     * {@link module:ui/dropdown/utils~focusChildOnDropdownOpen} to learn more about focus management in dropdowns.
     *
     * @observable
     */
    isOpen: boolean;
    /**
     * Controls whether the dropdown is enabled, i.e. it can be clicked and execute an action.
     *
     * See {@link module:ui/button/buttonview~ButtonView#isEnabled}.
     *
     * @observable
     */
    isEnabled: boolean;
    /**
     * (Optional) The additional CSS class set on the dropdown {@link #element}.
     *
     * @observable
     */
    class: string | undefined;
    /**
     * (Optional) The `id` attribute of the dropdown (i.e. to pair with a `<label>` element).
     *
     * @observable
     */
    id: string | undefined;
    /**
     * The position of the panel, relative to the dropdown.
     *
     * **Note**: When `'auto'`, the panel will use one of the remaining positions to stay
     * in the viewport, visible to the user. The positions correspond directly to
     * {@link module:ui/dropdown/dropdownview~DropdownView.defaultPanelPositions default panel positions}.
     *
     * **Note**: This value has an impact on the
     * {@link module:ui/dropdown/dropdownpanelview~DropdownPanelView#position} property
     * each time the panel becomes {@link #isOpen open}.
     *
     * @observable
     * @default 'auto'
     */
    panelPosition: PanelPosition | 'auto';
    /**
     * @observable
     */
    ariaDescribedById: string | undefined;
    /**
     * Creates an instance of the dropdown.
     *
     * Also see {@link #render}.
     *
     * @param locale The localization services instance.
     */
    constructor(locale: Locale | undefined, buttonView: DropdownButton & FocusableView, panelView: DropdownPanelView);
    /**
     * @inheritDoc
     */
    render(): void;
    /**
     * Focuses the {@link #buttonView}.
     */
    focus(): void;
    /**
     * Returns {@link #panelView panel} positions to be used by the
     * {@link module:utils/dom/position~getOptimalPosition `getOptimalPosition()`}
     * utility considering the direction of the language the UI of the editor is displayed in.
     */
    private get _panelPositions();
    /**
     * Returns the default position of the dropdown panel based on the direction of the UI language.
     * It is used when the {@link #panelPosition} is set to `'auto'` and the panel has not found a
     * suitable position to fit into the viewport.
     */
    private get _defaultPanelPositionName();
    /**
     * A set of positioning functions used by the dropdown view to determine
     * the optimal position (i.e. fitting into the browser viewport) of its
     * {@link module:ui/dropdown/dropdownview~DropdownView#panelView panel} when
     * {@link module:ui/dropdown/dropdownview~DropdownView#panelPosition} is set to 'auto'`.
     *
     * The available positioning functions are as follow:
     *
     * **South**
     *
     * * `south`
     *
     * ```
     *			[ Button ]
     *		+-----------------+
     *		|      Panel      |
     *		+-----------------+
     * ```
     *
     * * `southEast`
     *
     * ```
     *		[ Button ]
     *		+-----------------+
     *		|      Panel      |
     *		+-----------------+
     * ```
     *
     * * `southWest`
     *
     * ```
     *		         [ Button ]
     *		+-----------------+
     *		|      Panel      |
     *		+-----------------+
     * ```
     *
     * * `southMiddleEast`
     *
     * ```
     *		  [ Button ]
     *		+-----------------+
     *		|      Panel      |
     *		+-----------------+
     * ```
     *
     * * `southMiddleWest`
     *
     * ```
     *		       [ Button ]
     *		+-----------------+
     *		|      Panel      |
     *		+-----------------+
     * ```
     *
     * **North**
     *
     * * `north`
     *
     * ```
     *		+-----------------+
     *		|      Panel      |
     *		+-----------------+
     *		    [ Button ]
     * ```
     *
     * * `northEast`
     *
     * ```
     *		+-----------------+
     *		|      Panel      |
     *		+-----------------+
     *		[ Button ]
     * ```
     *
     * * `northWest`
     *
     * ```
     *		+-----------------+
     *		|      Panel      |
     *		+-----------------+
     *		         [ Button ]
     * ```
     *
     * * `northMiddleEast`
     *
     * ```
     *		+-----------------+
     *		|      Panel      |
     *		+-----------------+
     *		  [ Button ]
     * ```
     *
     * * `northMiddleWest`
     *
     * ```
     *		+-----------------+
     *		|      Panel      |
     *		+-----------------+
     *		       [ Button ]
     * ```
     *
     * Positioning functions are compatible with {@link module:utils/dom/position~DomPoint}.
     *
     * The name that position function returns will be reflected in dropdown panel's class that
     * controls its placement. See {@link module:ui/dropdown/dropdownview~DropdownView#panelPosition}
     * to learn more.
     */
    static defaultPanelPositions: Record<string, PositioningFunction>;
    /**
     * A function used to calculate the optimal position for the dropdown panel.
     */
    private static _getOptimalPosition;
}
/**
 * Fired when an item inside the dropdown is executed.
 *
 * **Note**: Only supported when dropdown was integrated with its child view using one of the helper functions:
 * {@link module:ui/dropdown/utils~addListToDropdown}, {@link module:ui/dropdown/utils~addToolbarToDropdown}, or
 * {@link module:ui/dropdown/utils~addMenuToDropdown}.
 *
 * When integrated with a list, it fires when a child of one of {@link module:ui/list/listitemview~ListItemView}s
 * fired `execute` event.
 *
 * When integrated with a toolbar, it fires when one of the buttons has been {@link module:ui/button/button~Button#event:execute executed}.
 *
 * When integrated with a nested menu, it fires when one of the menu buttons has been executed.
 *
 * In each case, the event is delegated from the component which fired it. It does not have additional parameters and `event.source` is the
 * original component.
 *
 * @eventName ~DropdownView#execute
 */
export type DropdownViewEvent = {
    name: 'execute';
    args: [];
};