@ckeditor/ckeditor5-ui 0.0.0-internal-20241017.0

package/src/bindings/submithandler.d.ts

@@ -0,0 +1,57 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @module ui/bindings/submithandler
+ */
+import type View from '../view.js';
+/**
+ * A handler useful for {@link module:ui/view~View views} working as HTML forms. It intercepts a native DOM
+ * `submit` event, prevents the default web browser behavior (navigation and page reload) and
+ * fires the `submit` event on a view instead. Such a custom event can be then used by any
+ * {@link module:utils/dom/emittermixin~DomEmitter emitter}, e.g. to serialize the form data.
+ *
+ * ```ts
+ * import submitHandler from '@ckeditor/ckeditor5-ui/src/bindings/submithandler';
+ *
+ * // ...
+ *
+ * class AnyFormView extends View {
+ * 	constructor() {
+ * 		super();
+ *
+ * 		// ...
+ *
+ * 		submitHandler( {
+ * 			view: this
+ * 		} );
+ * 	}
+ * }
+ *
+ * // ...
+ *
+ * const view = new AnyFormView();
+ *
+ * // A sample listener attached by an emitter working with the view.
+ * this.listenTo( view, 'submit', () => {
+ * 	saveTheFormData();
+ * 	hideTheForm();
+ * } );
+ * ```
+ *
+ * @param options Configuration options.
+ * @param options.view The view which DOM `submit` events should be handled.
+ */
+export default function submitHandler({ view }: {
+    view: View;
+}): void;
+/**
+ * Fired by {@link module:ui/bindings/submithandler~submitHandler} helper.
+ *
+ * @eventName module:ui/view~View#submit
+ */
+export type SubmitHandlerEvent = {
+    name: 'submit';
+    args: [];
+};

package/src/bindings/submithandler.js

@@ -0,0 +1,47 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * A handler useful for {@link module:ui/view~View views} working as HTML forms. It intercepts a native DOM
+ * `submit` event, prevents the default web browser behavior (navigation and page reload) and
+ * fires the `submit` event on a view instead. Such a custom event can be then used by any
+ * {@link module:utils/dom/emittermixin~DomEmitter emitter}, e.g. to serialize the form data.
+ *
+ * ```ts
+ * import submitHandler from '@ckeditor/ckeditor5-ui/src/bindings/submithandler';
+ *
+ * // ...
+ *
+ * class AnyFormView extends View {
+ * 	constructor() {
+ * 		super();
+ *
+ * 		// ...
+ *
+ * 		submitHandler( {
+ * 			view: this
+ * 		} );
+ * 	}
+ * }
+ *
+ * // ...
+ *
+ * const view = new AnyFormView();
+ *
+ * // A sample listener attached by an emitter working with the view.
+ * this.listenTo( view, 'submit', () => {
+ * 	saveTheFormData();
+ * 	hideTheForm();
+ * } );
+ * ```
+ *
+ * @param options Configuration options.
+ * @param options.view The view which DOM `submit` events should be handled.
+ */
+export default function submitHandler({ view }) {
+    view.listenTo(view.element, 'submit', (evt, domEvt) => {
+        domEvt.preventDefault();
+        view.fire('submit');
+    }, { useCapture: true });
+}

package/src/button/button.d.ts

@@ -0,0 +1,175 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @module ui/button/button
+ */
+/**
+ * The button interface. Implemented by, among others, {@link module:ui/button/buttonview~ButtonView},
+ * {@link module:ui/dropdown/button/splitbuttonview~SplitButtonView} and
+ * {@link module:ui/dropdown/button/dropdownbuttonview~DropdownButtonView}.
+ */
+export default interface Button {
+    /**
+     * The label of the button view visible to the user when {@link #withText} is `true`.
+     * It can also be used to create a {@link #tooltip}.
+     *
+     * @observable
+     */
+    label: string | undefined;
+    /**
+     * (Optional) The keystroke associated with the button, i.e. <kbd>CTRL+B</kbd>,
+     * in the string format compatible with {@link module:utils/keyboard}.
+     *
+     * **Note**: Use {@link module:ui/button/button~Button#withKeystroke} if you want to display
+     * the keystroke information next to the {@link module:ui/button/button~Button#label label}.
+     *
+     * @observable
+     */
+    keystroke: string | undefined;
+    /**
+     * (Optional) Tooltip of the button, i.e. displayed when hovering the button with the mouse cursor.
+     *
+     * * If defined as a `Boolean` (e.g. `true`), then combination of `label` and `keystroke` will be set as a tooltip.
+     * * If defined as a `String`, tooltip will equal the exact text of that `String`.
+     * * If defined as a `Function`, `label` and `keystroke` will be passed to that function, which is to return
+     * a string with the tooltip text.
+     *
+     * ```ts
+     * const view = new ButtonView( locale );
+     * view.tooltip = ( label, keystroke ) => `A tooltip for ${ label } and ${ keystroke }.`
+     * ```
+     *
+     * @observable
+     * @default false
+     */
+    tooltip: boolean | string | ((label: string, keystroke: string | undefined) => string);
+    /**
+     * (Optional) The position of the tooltip. See {@link module:ui/tooltipmanager~TooltipManager}
+     * to learn more about the tooltip system.
+     *
+     * **Note:** It makes sense only when the {@link #tooltip `tooltip` attribute} is defined.
+     *
+     * @observable
+     * @default 's'
+     */
+    tooltipPosition: 's' | 'n' | 'e' | 'w' | 'sw' | 'se';
+    /**
+     * The HTML type of the button.
+     *
+     * @observable
+     * @default 'button'
+     */
+    type: 'button' | 'submit' | 'reset' | 'menu';
+    /**
+     * Controls whether the button view is "on". It makes sense when a feature it represents
+     * is currently active, e.g. a bold button is "on" when the selection is in the bold text.
+     *
+     * To disable the button, use {@link #isEnabled} instead.
+     *
+     * @observable
+     * @default true
+     */
+    isOn: boolean;
+    /**
+     * Controls whether the button view is enabled, i.e. it can be clicked and execute an action.
+     *
+     * To change the "on" state of the button, use {@link #isOn} instead.
+     *
+     * @observable
+     * @default true
+     */
+    isEnabled: boolean;
+    /**
+     * Controls whether the button view is visible. Visible by default, buttons are hidden
+     * using a CSS class.
+     *
+     * @observable
+     * @default true
+     */
+    isVisible: boolean;
+    /**
+     * Controls whether the button view is a toggle button (two–state) for assistive technologies.
+     *
+     * @observable
+     * @default false
+     */
+    isToggleable: boolean;
+    /**
+     * (Optional) Controls whether the label of the button is hidden (e.g. an icon–only button).
+     *
+     * @observable
+     * @default false
+     */
+    withText: boolean;
+    /**
+     * (Optional) Controls whether the keystroke of the button is displayed next to its
+     * {@link module:ui/button/button~Button#label label}.
+     *
+     * **Note**: This property requires a {@link module:ui/button/button~Button#keystroke keystroke}
+     * to be defined in the first place.
+     *
+     * @observable
+     * @default false
+     */
+    withKeystroke: boolean;
+    /**
+     * (Optional) An XML {@link module:ui/icon/iconview~IconView#content content} of the icon.
+     * When defined, an `iconView` should be added to the button.
+     *
+     * The user must provide the entire XML string, not just the path. See the
+     * {@glink framework/architecture/ui-library#setting-label-icon-and-tooltip UI library} guide for details.
+     *
+     * @observable
+     */
+    icon: string | undefined;
+    /**
+     * (Optional) Controls the `tabindex` HTML attribute of the button. By default, the button is focusable
+     * but does not included in the <kbd>Tab</kbd> order.
+     *
+     * @observable
+     * @default -1
+     */
+    tabindex: number;
+    /**
+     * (Optional) The additional CSS class set on the button.
+     *
+     * @observable
+     */
+    class: string | undefined;
+    /**
+     * (Optional) The ARIA property reflected by the `aria-label` DOM attribute used by assistive technologies.
+     *
+     * @observable
+     */
+    ariaLabel?: string | undefined;
+    /**
+     * (Optional) The ARIA property reflected by the `aria-ariaLabelledBy` DOM attribute used by assistive technologies.
+     *
+     * @observable
+     */
+    ariaLabelledBy?: string | undefined;
+    /**
+     * (Optional) The property reflected by the `role` DOM attribute to be used by assistive technologies.
+     *
+     * @observable
+     */
+    role?: string | undefined;
+    /**
+     * (Optional) The value of the `style` attribute of the label.
+     *
+     * @observable
+     */
+    labelStyle: string | undefined;
+}
+/**
+ * Fired when the button view is clicked. It won't be fired when the button {@link module:ui/button/button~Button#isEnabled}
+ * is `false`.
+ *
+ * @eventName ~Button#execute
+ */
+export type ButtonExecuteEvent = {
+    name: 'execute';
+    args: [];
+};

package/src/button/button.js

@@ -0,0 +1,5 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+export {};

package/src/button/buttonlabel.d.ts

@@ -0,0 +1,34 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @module ui/button/buttonlabel
+*/
+import type View from '../view.js';
+/**
+ * The button label interface. Implemented by the {@link module:ui/button/buttonlabelview~ButtonLabelView}
+ * and any label view that can be used with the {@link module:ui/button/buttonview~ButtonView}.
+ */
+export default interface ButtonLabel extends View {
+    /**
+     * The `id` attribute of the button label. It is used for accessibility purposes
+     * to describe the button.
+     *
+     * @observable
+     */
+    id: string | undefined;
+    /**
+     * The `style` attribute of the button label. It allows customizing the presentation
+     * of the label.
+     *
+     * @observable
+     */
+    style: string | undefined;
+    /**
+     * The human-readable text of the label.
+     *
+     * @observable
+     */
+    text: string | undefined;
+}

package/src/button/buttonlabel.js

@@ -0,0 +1,5 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+export {};

package/src/button/buttonlabelview.d.ts

@@ -0,0 +1,31 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @module ui/button/buttonlabelview
+ */
+import View from '../view.js';
+import type ButtonLabel from './buttonlabel.js';
+/**
+ * A default implementation of the button view's label. It comes with a dynamic text support
+ * via {@link module:ui/button/buttonlabelview~ButtonLabelView#text} property.
+ */
+export default class ButtonLabelView extends View implements ButtonLabel {
+    /**
+     * @inheritDoc
+     */
+    id: string | undefined;
+    /**
+     * @inheritDoc
+     */
+    style: string | undefined;
+    /**
+     * @inheritDoc
+     */
+    text: string | undefined;
+    /**
+     * @inheritDoc
+     */
+    constructor();
+}

package/src/button/buttonlabelview.js

@@ -0,0 +1,42 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @module ui/button/buttonlabelview
+ */
+import View from '../view.js';
+/**
+ * A default implementation of the button view's label. It comes with a dynamic text support
+ * via {@link module:ui/button/buttonlabelview~ButtonLabelView#text} property.
+ */
+export default class ButtonLabelView extends View {
+    /**
+     * @inheritDoc
+     */
+    constructor() {
+        super();
+        this.set({
+            style: undefined,
+            text: undefined,
+            id: undefined
+        });
+        const bind = this.bindTemplate;
+        this.setTemplate({
+            tag: 'span',
+            attributes: {
+                class: [
+                    'ck',
+                    'ck-button__label'
+                ],
+                style: bind.to('style'),
+                id: bind.to('id')
+            },
+            children: [
+                {
+                    text: bind.to('text')
+                }
+            ]
+        });
+    }
+}

package/src/button/buttonview.d.ts

@@ -0,0 +1,197 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @module ui/button/buttonview
+ */
+import View from '../view.js';
+import IconView from '../icon/iconview.js';
+import type ViewCollection from '../viewcollection.js';
+import type { default as Button } from './button.js';
+import type ButtonLabel from './buttonlabel.js';
+import { type Locale } from '@ckeditor/ckeditor5-utils';
+import '../../theme/components/button/button.css';
+/**
+ * The button view class.
+ *
+ * ```ts
+ * const view = new ButtonView();
+ *
+ * view.set( {
+ * 	label: 'A button',
+ * 	keystroke: 'Ctrl+B',
+ * 	tooltip: true,
+ * 	withText: true
+ * } );
+ *
+ * view.render();
+ *
+ * document.body.append( view.element );
+ * ```
+ */
+export default class ButtonView extends View<HTMLButtonElement> implements Button {
+    /**
+     * Collection of the child views inside of the button {@link #element}.
+     */
+    readonly children: ViewCollection;
+    /**
+     * Label of the button view. Its text is configurable using the {@link #label label attribute}.
+     *
+     * If not configured otherwise in the `constructor()`, by default the label is an instance
+     * of {@link module:ui/button/buttonlabelview~ButtonLabelView}.
+     */
+    readonly labelView: ButtonLabel;
+    /**
+     * The icon view of the button. Will be added to {@link #children} when the
+     * {@link #icon icon attribute} is defined.
+     */
+    readonly iconView: IconView;
+    /**
+     * A view displaying the keystroke of the button next to the {@link #labelView label}.
+     * Added to {@link #children} when the {@link #withKeystroke `withKeystroke` attribute}
+     * is defined.
+     */
+    readonly keystrokeView: View;
+    /**
+     * @inheritDoc
+     */
+    class: string | undefined;
+    /**
+     * @inheritDoc
+     */
+    labelStyle: string | undefined;
+    /**
+     * @inheritDoc
+     */
+    icon: string | undefined;
+    /**
+     * @inheritDoc
+     */
+    isEnabled: boolean;
+    /**
+     * @inheritDoc
+     */
+    isOn: boolean;
+    /**
+     * @inheritDoc
+     */
+    isVisible: boolean;
+    /**
+     * @inheritDoc
+     */
+    isToggleable: boolean;
+    /**
+     * @inheritDoc
+     */
+    keystroke: string | undefined;
+    /**
+     * @inheritDoc
+     */
+    label: string | undefined;
+    /**
+     * @inheritDoc
+     */
+    tabindex: number;
+    /**
+     * @inheritDoc
+     */
+    tooltip: Button['tooltip'];
+    /**
+     * @inheritDoc
+     */
+    tooltipPosition: Button['tooltipPosition'];
+    /**
+     * @inheritDoc
+     */
+    type: Button['type'];
+    /**
+     * @inheritDoc
+     */
+    withText: boolean;
+    /**
+     * @inheritDoc
+     */
+    withKeystroke: boolean;
+    /**
+     * @inheritDoc
+     */
+    role: string | undefined;
+    /**
+     * @inheritDoc
+     */
+    ariaLabel?: string | undefined;
+    /**
+     * @inheritDoc
+     */
+    ariaLabelledBy: string | undefined;
+    /**
+     * Aria-pressed attribute of element. It is calculated based on {@link #isToggleable isToggleable} and {@link #role}.
+     * It's set to true if the button is on and the role is not checkable.
+     *
+     * @readonly
+     * @internal
+     */
+    _ariaPressed: string | false;
+    /**
+     * Aria-checked attribute of element. It is calculated based on {@link #isToggleable isToggleable} and {@link #role}.
+     * It's set to true if the button is on and the role is checkable.
+     *
+     * @readonly
+     * @internal
+     */
+    _ariaChecked: string | false;
+    /**
+     * Tooltip of the button bound to the template.
+     *
+     * @see #tooltip
+     * @see module:ui/button/buttonview~ButtonView#_getTooltipString
+     * @internal
+     * @observable
+     */
+    _tooltipString: string;
+    /**
+     * Delayed focus function for focus handling in Safari.
+     */
+    private _focusDelayed;
+    /**
+     * Creates an instance of the button view class.
+     *
+     * @param locale The {@link module:core/editor/editor~Editor#locale} instance.
+     * @param labelView The instance of the button's label. If not provided, an instance of
+     * {@link module:ui/button/buttonlabelview~ButtonLabelView} is used.
+     */
+    constructor(locale?: Locale, labelView?: ButtonLabel);
+    /**
+     * @inheritDoc
+     */
+    render(): void;
+    /**
+     * Focuses the {@link #element} of the button.
+     */
+    focus(): void;
+    /**
+     * @inheritDoc
+     */
+    destroy(): void;
+    /**
+     * Binds the label view instance it with button attributes.
+     */
+    private _setupLabelView;
+    /**
+     * Creates a view that displays a keystroke next to a {@link #labelView label }
+     * and binds it with button attributes.
+     */
+    private _createKeystrokeView;
+    /**
+     * Gets the text for the tooltip from the combination of
+     * {@link #tooltip}, {@link #label} and {@link #keystroke} attributes.
+     *
+     * @see #tooltip
+     * @see #_tooltipString
+     * @param tooltip Button tooltip.
+     * @param label Button label.
+     * @param keystroke Button keystroke.
+     */
+    private _getTooltipString;
+}