js-draw 0.25.1 → 1.0.1

package/src/toolbar/localization.ts

@@ -13,11 +13,13 @@ export interface ToolbarLocalization {
 	image: string;
 	inputAltText: string;
 	chooseFile: string;
+	dragAndDropHereOrBrowse: string; // Uses {{curly braces}} to bold text
 	cancel: string;
 	submit: string;
 	roundedTipPen: string;
 	flatTipPen: string;
-	selectPenType: string;
+	selectPenTip: string;
+	selectShape: string;
 	colorLabel: string;
 	pen: string;
 	eraser: string;
@@ -32,11 +34,14 @@ export interface ToolbarLocalization {
 	clickToPickColorAnnouncement: string;
 	colorSelectionCanceledAnnouncement: string;
 
-	reformatSelection: string;
 	undo: string;
 	redo: string;
+	exit: string;
+	save: string;
+
 	zoom: string;
 	resetView: string;
+	reformatSelection: string;
 	selectionToolKeyboardShortcuts: string;
 	paste: string;
 	documentProperties: string;
@@ -46,10 +51,16 @@ export interface ToolbarLocalization {
 	useGridOption: string;
 	toggleOverflow: string,
 
+	about: string;
+	inputStabilization: string;
+
 	errorImageHasZeroSize: string;
 
+	// closeSidebar is used for accessibility in a button label.
+	closeSidebar: (toolName: string)=>string;
 	dropdownShown: (toolName: string)=> string;
 	dropdownHidden: (toolName: string)=> string;
+
 	zoomLevel: (zoomPercentage: number)=> string;
 	colorChangedAnnouncement: (color: string)=> string;
 	imageSize: (size: number, units: string)=> string;
@@ -64,36 +75,44 @@ export const defaultToolbarLocalization: ToolbarLocalization = {
 	zoom: 'Zoom',
 	image: 'Image',
 	reformatSelection: 'Format selection',
-	inputAltText: 'Alt text: ',
-	chooseFile: 'Choose file: ',
+	inputAltText: 'Alt text',
+	chooseFile: 'Choose file',
+	dragAndDropHereOrBrowse: 'Drag and drop here\nor\n{{browse}}',
 	submit: 'Submit',
 	cancel: 'Cancel',
 	resetView: 'Reset view',
-	thicknessLabel: 'Thickness: ',
-	colorLabel: 'Color: ',
-	fontLabel: 'Font: ',
-	textSize: 'Size: ',
+	thicknessLabel: 'Thickness',
+	colorLabel: 'Color',
+	fontLabel: 'Font',
+	textSize: 'Size',
 	resizeImageToSelection: 'Resize image to selection',
 	deleteSelection: 'Delete selection',
 	duplicateSelection: 'Duplicate selection',
+
+	exit: 'Exit',
+	save: 'Save',
 	undo: 'Undo',
 	redo: 'Redo',
-	selectPenType: 'Pen type: ',
+
+	selectPenTip: 'Pen tip',
+	selectShape: 'Shape',
 	pickColorFromScreen: 'Pick color from screen',
 	clickToPickColorAnnouncement: 'Click on the screen to pick a color',
 	colorSelectionCanceledAnnouncement: 'Color selection canceled',
 	selectionToolKeyboardShortcuts: 'Selection tool: Use arrow keys to move selected items, lowercase/uppercase ‘i’ and ‘o’ to resize.',
 	documentProperties: 'Page',
-	backgroundColor: 'Background Color: ',
-	imageWidthOption: 'Width: ',
-	imageHeightOption: 'Height: ',
-	useGridOption: 'Grid: ',
+	backgroundColor: 'Background color',
+	imageWidthOption: 'Width',
+	imageHeightOption: 'Height',
+	useGridOption: 'Grid',
 	toggleOverflow: 'More',
+	about: 'About',
+	inputStabilization: 'Input stabilization',
 
 	touchPanning: 'Touchscreen panning',
 
-	roundedTipPen: 'Rounded Tip',
-	flatTipPen: 'Flat Tip',
+	roundedTipPen: 'Round',
+	flatTipPen: 'Flat',
 	arrowPen: 'Arrow',
 	linePen: 'Line',
 	outlinedRectanglePen: 'Outlined rectangle',
@@ -103,8 +122,11 @@ export const defaultToolbarLocalization: ToolbarLocalization = {
 
 	paste: 'Paste',
 
-	dropdownShown: (toolName) => `Dropdown for ${toolName} shown`,
-	dropdownHidden: (toolName) => `Dropdown for ${toolName} hidden`,
+
+	closeSidebar: (toolName: string) => `Close sidebar for ${toolName}`,
+	dropdownShown: (toolName) => `Menu for ${toolName} shown`,
+	dropdownHidden: (toolName) => `Menu for ${toolName} hidden`,
+
 	zoomLevel: (zoomPercent: number) => `Zoom: ${zoomPercent}%`,
 	colorChangedAnnouncement: (color: string) => `Color changed to ${color}`,
 	imageSize: (size: number, units: string) => `Image size: ${size} ${units}`,

package/src/toolbar/toolbar.scss

@@ -0,0 +1,11 @@
+@use "./widgets/InsertImageWidget.scss";
+@use "./widgets/OverflowWidget.css";
+@use "./widgets/PenToolWidget.css";
+@use "./widgets/HandToolWidget.scss";
+@use "./widgets/SelectionToolWidget.scss";
+@use "./widgets/DocumentPropertiesWidget.scss";
+@use "./widgets/components/components.scss";
+
+@use "./AbstractToolbar.scss";
+@use "./EdgeToolbar.scss";
+@use "./DropdownToolbar.scss";

package/src/toolbar/types.ts

@@ -1,5 +1,13 @@
+import IconProvider from './IconProvider';
+import type { ToolbarLocalization } from './localization';
 
 export interface ActionButtonIcon {
 	icon: Element;
 	label: string;
 }
+
+export interface ToolbarContext {
+	announceForAccessibility(text: string): void;
+	localization: ToolbarLocalization;
+	icons: IconProvider;
+}

package/src/toolbar/widgets/ActionButtonWidget.ts

@@ -33,7 +33,7 @@ export default class ActionButtonWidget extends BaseWidget {
 		return false;
 	}
 
-	public override canBeInOverflowMenu(): boolean {
-		return !this.mustBeToplevel;
+	public override mustBeInToplevelMenu(): boolean {
+		return this.mustBeToplevel;
 	}
 }

package/src/toolbar/widgets/BaseToolWidget.ts

@@ -1,8 +1,15 @@
 import Editor from '../../Editor';
 import BaseTool from '../../tools/BaseTool';
-import { EditorEventType, KeyPressEvent } from '../../types';
+import { EditorEventType } from '../../types';
+import { KeyPressEvent } from '../../inputEvents';
 import { ToolbarLocalization } from '../localization';
 import BaseWidget from './BaseWidget';
+import { toolbarCSSPrefix } from '../constants';
+
+const isToolWidgetFocused = () => {
+	const currentFocus = [...document.querySelectorAll('*:focus')];
+	return currentFocus.length && currentFocus.some(elem => elem.classList.contains(`${toolbarCSSPrefix}button`));
+};
 
 export default abstract class BaseToolWidget extends BaseWidget {
 	public constructor(
@@ -20,6 +27,14 @@ export default abstract class BaseToolWidget extends BaseWidget {
 
 			if (toolEvt.tool === targetTool) {
 				this.setSelected(true);
+
+				// Transfer focus to the current button, only if another toolbar button is
+				// focused.
+				// This prevents pressing "space" from triggering a different action when
+				// the current is selected.
+				if (isToolWidgetFocused()) {
+					this.focus();
+				}
 			}
 		});
 
@@ -39,6 +54,7 @@ export default abstract class BaseToolWidget extends BaseWidget {
 		if (this.hasDropdown) {
 			if (!this.targetTool.isEnabled()) {
 				this.targetTool.setEnabled(true);
+				this.activateDropdown();
 			} else {
 				this.setDropdownVisible(!this.isDropdownVisible());
 			}

package/src/toolbar/widgets/BaseWidget.ts

@@ -1,22 +1,37 @@
 import Editor from '../../Editor';
-import { DispatcherEventListener } from '../../EventDispatcher';
 import ToolbarShortcutHandler from '../../tools/ToolbarShortcutHandler';
-import { EditorEventType, InputEvtType, KeyPressEvent } from '../../types';
-import { toolbarCSSPrefix } from '../HTMLToolbar';
+import { KeyPressEvent, keyPressEventFromHTMLEvent, keyUpEventFromHTMLEvent } from '../../inputEvents';
+import { toolbarCSSPrefix } from '../constants';
 import { ToolbarLocalization } from '../localization';
+import DropdownLayoutManager from './layout/DropdownLayoutManager';
+import { ToolMenu, WidgetContentLayoutManager } from './layout/types';
 
 export type SavedToolbuttonState = Record<string, any>;
 
+/**
+ * A set of labels that allow toolbar themes to treat buttons differently.
+ */
+export enum ToolbarWidgetTag {
+	Save = 'save',
+	Exit = 'exit',
+	Undo = 'undo',
+	Redo = 'redo',
+}
+
 export default abstract class BaseWidget {
 	protected readonly container: HTMLElement;
 	private button: HTMLElement;
 	private icon: Element|null;
-	private dropdownContainer: HTMLElement;
+	private layoutManager: WidgetContentLayoutManager;
+	private dropdown: ToolMenu|null = null;
+	private dropdownContent: HTMLElement;
 	private dropdownIcon: Element;
 	private label: HTMLLabelElement;
 	#hasDropdown: boolean;
 	private disabled: boolean = false;
 
+	#tags: (ToolbarWidgetTag|string)[] = [];
+
 	// Maps subWidget IDs to subWidgets.
 	private subWidgets: Record<string, BaseWidget> = {};
 
@@ -26,16 +41,24 @@ export default abstract class BaseWidget {
 	public constructor(
 		protected editor: Editor,
 		protected id: string,
-		localizationTable?: ToolbarLocalization,
+		localizationTable?: ToolbarLocalization
 	) {
 		this.localizationTable = localizationTable ?? editor.localization;
 
+		// Default layout manager
+		const defaultLayoutManager = new DropdownLayoutManager(
+			(text) => this.editor.announceForAccessibility(text),
+			this.localizationTable
+		);
+		defaultLayoutManager.connectToEditorNotifier(editor.notifier);
+		this.layoutManager = defaultLayoutManager;
+
 		this.icon = null;
 		this.container = document.createElement('div');
-		this.container.classList.add(`${toolbarCSSPrefix}toolContainer`);
-		this.dropdownContainer = document.createElement('div');
-		this.dropdownContainer.classList.add(`${toolbarCSSPrefix}dropdown`);
-		this.dropdownContainer.classList.add('hidden');
+		this.container.classList.add(
+			`${toolbarCSSPrefix}toolContainer`, `${toolbarCSSPrefix}toolButtonContainer`
+		);
+		this.dropdownContent = document.createElement('div');
 		this.#hasDropdown = false;
 
 		this.button = document.createElement('div');
@@ -57,6 +80,43 @@ export default abstract class BaseWidget {
 		return this.id;
 	}
 
+	/**
+	 * Note: Tags should be set *before* a tool widget is added to a toolbar.
+	 *
+	 *
+	 * Associates tags with this widget that can be used by toolbar themes
+	 * to customize the layout/appearance of this button. Prefer tags in
+	 * the `ToolbarWidgetTag` enum, where possible.
+	 *
+	 * In addition to being readable from the {@link getTags} method, tags are
+	 * added to a button's main container as CSS classes with the `toolwidget-tag--` prefix.
+	 *
+	 * For example, the `undo` tag would result in `toolwidget-tag--undo`
+	 * being added to the button's container's class list.
+	 *
+	 */
+	public setTags(tags: (string|ToolbarWidgetTag)[]) {
+		const toClassName = (tag: string) => {
+			return `toolwidget-tag--${tag}`;
+		};
+
+		// Remove CSS classes associated with old tags
+		for (const tag of this.#tags) {
+			this.container.classList.remove(toClassName(tag));
+		}
+
+		this.#tags = [...tags];
+
+		// Add new CSS classes
+		for (const tag of this.#tags) {
+			this.container.classList.add(toClassName(tag));
+		}
+	}
+
+	public getTags() {
+		return [ ...this.#tags ];
+	}
+
 	/**
 	 * Returns the ID of this widget in `container`. Adds a suffix to this' ID
 	 * if an item in `container` already has this' ID.
@@ -65,6 +125,8 @@ export default abstract class BaseWidget {
 	 * `container = { 'foo': somethingNotThis, 'foo-1': somethingElseNotThis }`, this method
 	 * returns `foo-2` because elements with IDs `foo` and `foo-1` are already present in
 	 * `container`.
+	 *
+	 * If `this` is already in `container`, returns the id given to `this` in the container.
 	 */
 	public getUniqueIdIn(container: Record<string, BaseWidget>): string {
 		let id = this.getId();
@@ -97,7 +159,12 @@ export default abstract class BaseWidget {
 		return true;
 	}
 
+	/** @deprecated Renamed to `setUpButtonEventListeners`. */
 	protected setupActionBtnClickListener(button: HTMLElement) {
+		return this.setUpButtonEventListeners(button);
+	}
+
+	protected setUpButtonEventListeners(button: HTMLElement) {
 		const clickTriggers = { Enter: true, ' ': true, };
 		button.onkeydown = (evt) => {
 			let handled = false;
@@ -111,12 +178,8 @@ export default abstract class BaseWidget {
 
 			// If we didn't do anything with the event, send it to the editor.
 			if (!handled) {
-				handled = this.editor.toolController.dispatchInputEvent({
-					kind: InputEvtType.KeyPressEvent,
-					key: evt.key,
-					ctrlKey: evt.ctrlKey || evt.metaKey,
-					altKey: evt.altKey,
-				});
+				const editorEvent = keyPressEventFromHTMLEvent(evt);
+				handled = this.editor.toolController.dispatchInputEvent(editorEvent);
 			}
 
 			if (handled) {
@@ -124,20 +187,16 @@ export default abstract class BaseWidget {
 			}
 		};
 
-		button.onkeyup = evt => {
-			if (evt.key in clickTriggers) {
+		button.onkeyup = htmlEvent => {
+			if (htmlEvent.key in clickTriggers) {
 				return;
 			}
 
-			const handled = this.editor.toolController.dispatchInputEvent({
-				kind: InputEvtType.KeyUpEvent,
-				key: evt.key,
-				ctrlKey: evt.ctrlKey || evt.metaKey,
-				altKey: evt.altKey,
-			});
+			const event = keyUpEventFromHTMLEvent(htmlEvent);
+			const handled = this.editor.toolController.dispatchInputEvent(event);
 
 			if (handled) {
-				evt.preventDefault();
+				htmlEvent.preventDefault();
 			}
 		};
 
@@ -146,6 +205,11 @@ export default abstract class BaseWidget {
 				this.handleClick();
 			}
 		};
+
+		// Prevent double-click zoom on some devices.
+		button.ondblclick = event => {
+			event.preventDefault();
+		};
 	}
 
 	// Add a listener that is triggered when a key is pressed.
@@ -169,7 +233,18 @@ export default abstract class BaseWidget {
 		this.subWidgets[id] = widget;
 	}
 
-	private toolbarWidgetToggleListener: DispatcherEventListener|null = null;
+	public setLayoutManager(manager: WidgetContentLayoutManager) {
+		if (manager === this.layoutManager) {
+			return;
+		}
+
+		this.layoutManager = manager;
+		if (this.container.parentElement) {
+			// Trigger a re-creation of this' content
+			this.addTo(this.container.parentElement);
+		}
+	}
+
 
 	/**
 	 * Adds this to `parent`.
@@ -190,7 +265,7 @@ export default abstract class BaseWidget {
 		}
 
 		// Click functionality
-		this.setupActionBtnClickListener(this.button);
+		this.setUpButtonEventListeners(this.button);
 
 		// Clear anything already in this.container.
 		this.container.replaceChildren();
@@ -200,29 +275,39 @@ export default abstract class BaseWidget {
 
 		// Clear the dropdownContainer in case this element is being moved to another
 		// parent.
-		this.dropdownContainer.replaceChildren();
-		this.#hasDropdown = this.fillDropdown(this.dropdownContainer);
+		this.dropdownContent.replaceChildren();
+		this.#hasDropdown = this.fillDropdown(this.dropdownContent);
 		if (this.#hasDropdown) {
+			this.button.classList.add('has-dropdown');
+
+			// We're re-creating the dropdown.
+			this.dropdown?.destroy();
+
 			this.dropdownIcon = this.createDropdownIcon();
 			this.button.appendChild(this.dropdownIcon);
-			this.container.appendChild(this.dropdownContainer);
 
-			if (this.toolbarWidgetToggleListener) {
-				this.toolbarWidgetToggleListener.remove();
-			}
+			this.dropdown = this.layoutManager.createToolMenu({
+				target: this.button,
+				getTitle: () => this.getTitle(),
+				isToplevel: () => this.toplevel,
+			});
 
-			this.toolbarWidgetToggleListener = this.editor.notifier.on(EditorEventType.ToolbarDropdownShown, (evt) => {
-				if (
-					evt.kind === EditorEventType.ToolbarDropdownShown
-					&& evt.parentWidget !== this
+			this.dropdown.visible.onUpdate(visible => {
+				if (visible) {
+					this.container.classList.add('dropdownVisible');
+				} else {
+					this.container.classList.remove('dropdownVisible');
+				}
 
-					// Don't hide if a submenu wash shown (it might be a submenu of
-					// the current menu).
-					&& evt.parentWidget.toplevel
-				) {
-					this.setDropdownVisible(false);
+				// Auto-focus this component's button when the dropdown hides --
+				// this ensures that keyboard focus goes to a reasonable location when
+				// the user closes a menu.
+				if (!visible) {
+					this.focus();
 				}
 			});
+
+			this.dropdown.appendChild(this.dropdownContent);
 		}
 
 		this.setDropdownVisible(false);
@@ -235,17 +320,38 @@ export default abstract class BaseWidget {
 		return this.container;
 	}
 
+	public focus() {
+		this.button.focus();
+	}
+
+	/**
+	 * @internal
+	 */
+	public addCSSClassToContainer(className: string) {
+		this.container.classList.add(className);
+	}
+
+	public removeCSSClassFromContainer(className: string) {
+		this.container.classList.remove(className);
+	}
+
+	public remove() {
+		this.container.remove();
+	}
 
 	protected updateIcon() {
-		const newIcon = this.createIcon();
+		let newIcon = this.createIcon();
 
-		if (newIcon) {
-			this.icon?.replaceWith(newIcon);
-			this.icon = newIcon;
-			this.icon.classList.add(`${toolbarCSSPrefix}icon`);
+		if (!newIcon) {
+			newIcon = document.createElement('div');
+			this.container.classList.add('no-icon');
 		} else {
-			this.icon?.remove();
+			this.container.classList.remove('no-icon');
 		}
+
+		this.icon?.replaceWith(newIcon);
+		this.icon = newIcon;
+		this.icon.classList.add(`${toolbarCSSPrefix}icon`);
 	}
 
 	public setDisabled(disabled: boolean) {
@@ -281,66 +387,40 @@ export default abstract class BaseWidget {
 		}
 	}
 
-	private hideDropdownTimeout: any|null = null;
 
 	protected setDropdownVisible(visible: boolean) {
-		const currentlyVisible = this.container.classList.contains('dropdownVisible');
-		if (currentlyVisible === visible) {
-			return;
-		}
-
-		// If waiting to hide the dropdown, cancel it.
-		if (this.hideDropdownTimeout) {
-			clearTimeout(this.hideDropdownTimeout);
-			this.hideDropdownTimeout = null;
-			this.dropdownContainer.classList.remove('hiding');
-			this.repositionDropdown();
-		}
-
-
-		const animationDuration = 150; // ms
-
 		if (visible) {
-			this.dropdownContainer.classList.remove('hidden');
-			this.container.classList.add('dropdownVisible');
-			this.editor.announceForAccessibility(
-				this.localizationTable.dropdownShown(this.getTitle())
-			);
-
-			this.editor.notifier.dispatch(EditorEventType.ToolbarDropdownShown, {
-				kind: EditorEventType.ToolbarDropdownShown,
-				parentWidget: this,
-			});
-
-			this.repositionDropdown();
+			this.dropdown?.requestShow();
 		} else {
-			this.container.classList.remove('dropdownVisible');
-			this.editor.announceForAccessibility(
-				this.localizationTable.dropdownHidden(this.getTitle())
-			);
-
-			this.dropdownContainer.classList.add('hiding');
-
-			// Hide the dropdown *slightly* before the animation finishes. This
-			// prevents flickering in some browsers.
-			const hideDelay = animationDuration * 0.95;
-
-			this.hideDropdownTimeout = setTimeout(() => {
-				this.dropdownContainer.classList.add('hidden');
-				this.dropdownContainer.classList.remove('hiding');
-				this.repositionDropdown();
-			}, hideDelay);
+			this.dropdown?.requestHide();
 		}
+	}
+
+	/**
+	 * Only used by some layout managers.
+	 * In those layout managers, makes this dropdown visible.
+	 */
+	protected activateDropdown() {
+		this.dropdown?.onActivated();
+	}
 
-		// Animate
-		const animationName = `var(--dropdown-${
-			visible ? 'show' : 'hide'
-		}-animation)`;
-		this.dropdownContainer.style.animation = `${animationDuration}ms ease ${animationName}`;
+	/**
+	 * Returns `true` if this widget must always be in a toplevel menu and not
+	 * in a scrolling/overflow menu.
+	 *
+	 * This method can be overidden to override the default of `true`.
+	 */
+	public mustBeInToplevelMenu(): boolean {
+		return false;
 	}
 
+	/**
+	 * Returns true iff this widget can be in a nontoplevel menu.
+	 *
+	 * @deprecated Use `!mustBeInToplevelMenu()` instead.
+	 */
 	public canBeInOverflowMenu(): boolean {
-		return true;
+		return !this.mustBeInToplevelMenu();
 	}
 
 	public getButtonWidth(): number {
@@ -355,26 +435,13 @@ export default abstract class BaseWidget {
 		this.container.style.display = hidden ? 'none' : '';
 	}
 
-	protected repositionDropdown() {
-		const dropdownBBox = this.dropdownContainer.getBoundingClientRect();
-		const screenWidth = document.body.clientWidth;
-
-		if (dropdownBBox.left > screenWidth / 2) {
-			// Use .translate so as not to conflict with CSS animating the
-			// transform property.
-			this.dropdownContainer.style.translate = `calc(${this.button.clientWidth + 'px'} - 100%) 0`;
-		} else {
-			this.dropdownContainer.style.translate = '';
-		}
-	}
-
 	/** Set whether the widget is contained within another. @internal */
 	public setIsToplevel(toplevel: boolean) {
 		this.toplevel = toplevel;
 	}
 
 	protected isDropdownVisible(): boolean {
-		return !this.dropdownContainer.classList.contains('hidden');
+		return this.dropdown?.visible?.get() ?? false;
 	}
 
 	protected isSelected(): boolean {

package/src/toolbar/widgets/DocumentPropertiesWidget.scss

@@ -0,0 +1,7 @@
+
+.toolbar-document-properties-widget {
+	button.about-button {
+		width: 100%;
+		text-align: end;
+	}
+}