js-draw 1.14.0 → 1.16.0

package/dist/mjs/toolbar/EdgeToolbar.mjs

@@ -4,6 +4,7 @@ import  EdgeToolbarLayoutManager  from './widgets/layout/EdgeToolbarLayoutManage
 import  { MutableReactiveValue, ReactiveValue }  from '../util/ReactiveValue.mjs';
 import  AbstractToolbar  from './AbstractToolbar.mjs';
 import  stopPropagationOfScrollingWheelEvents  from '../util/stopPropagationOfScrollingWheelEvents.mjs';
+import  makeDraggable  from './utils/makeDraggable.mjs';
 /**
  * Creates an `EdgeToolbar`.
  *
@@ -39,6 +40,7 @@ export default class EdgeToolbar extends AbstractToolbar {
     /** @internal */
     constructor(editor, parent, localizationTable) {
         super(editor, localizationTable);
+        this.clearDragListeners = null;
         this.toolbarContainer = document.createElement('div');
         this.toolbarContainer.classList.add(`${toolbarCSSPrefix}root`);
         this.toolbarContainer.classList.add(`${toolbarCSSPrefix}element`);
@@ -124,8 +126,11 @@ export default class EdgeToolbar extends AbstractToolbar {
             // to animate it to 1.
             this.menuContainer.style.opacity = '0';
         }
+        const prefersReduceMotion = window.matchMedia?.('(prefers-reduced-motion: reduce)') ?? '';
         this.sidebarVisible.onUpdate(visible => {
             const animationProperties = `${animationDuration}ms ease`;
+            // We need to use different animations when reducing motion.
+            const reduceMotion = prefersReduceMotion.matches ? '-reduce-motion' : '';
             if (visible) {
                 this.sidebarY.set(this.snappedSidebarY());
                 if (animationTimeout) {
@@ -133,8 +138,10 @@ export default class EdgeToolbar extends AbstractToolbar {
                     animationTimeout = null;
                 }
                 this.menuContainer.style.display = '';
-                this.sidebarContainer.style.animation = `${animationProperties} ${toolbarCSSPrefix}-edgemenu-transition-in`;
-                this.menuContainer.style.animation = `${animationProperties} ${toolbarCSSPrefix}-edgemenu-container-transition-in`;
+                this.sidebarContainer.style.animation =
+                    `${animationProperties} ${toolbarCSSPrefix}-edgemenu-transition-in${reduceMotion}`;
+                this.menuContainer.style.animation =
+                    `${animationProperties} ${toolbarCSSPrefix}-edgemenu-container-transition-in${reduceMotion}`;
                 this.menuContainer.style.opacity = '1';
                 // Focus the close button when first shown, but prevent scroll because the button
                 // is likely at the bottom of the screen (and we want the full sidebar to remain
@@ -144,8 +151,10 @@ export default class EdgeToolbar extends AbstractToolbar {
             else {
                 this.closeColorPickers();
                 if (animationTimeout === null) {
-                    this.sidebarContainer.style.animation = ` ${animationProperties} ${toolbarCSSPrefix}-edgemenu-transition-out`;
-                    this.menuContainer.style.animation = `${animationProperties} ${toolbarCSSPrefix}-edgemenu-container-transition-out`;
+                    this.sidebarContainer.style.animation =
+                        `${animationProperties} ${toolbarCSSPrefix}-edgemenu-transition-out${reduceMotion}`;
+                    this.menuContainer.style.animation =
+                        `${animationProperties} ${toolbarCSSPrefix}-edgemenu-container-transition-out${reduceMotion}`;
                     // Manually set the container's opacity to prevent flickering when closing
                     // the toolbar.
                     this.menuContainer.style.opacity = '0';
@@ -254,15 +263,12 @@ export default class EdgeToolbar extends AbstractToolbar {
         this.toolbarContainer.remove();
         this.menuContainer.remove();
         this.toolRowResizeObserver.disconnect();
+        this.clearDragListeners?.();
     }
     initDragListeners() {
-        let lastX = 0;
-        let lastY = 0;
-        let startX = 0;
-        let startY = 0;
-        let pointerDown = false;
-        let capturedPointerId = null;
         const dragElements = [this.closeButton, this.sidebarContainer, this.sidebarContent];
+        // Forward longer touch events from the menu background to the
+        // editor (and close the sidebar).
         this.manageListener(this.editor.handlePointerEventsExceptClicksFrom(this.menuContainer, (eventName, event) => {
             if (event.target === this.menuContainer) {
                 if (eventName === 'pointerdown') {
@@ -281,113 +287,27 @@ export default class EdgeToolbar extends AbstractToolbar {
         }, (_eventName, event) => {
             return event.target === this.menuContainer;
         }));
-        const isDraggableElement = (element) => {
-            if (!element) {
-                return false;
-            }
-            if (dragElements.includes(element)) {
-                return true;
-            }
-            // Some inputs handle dragging themselves. Don't also interpret such gestures
-            // as dragging the dropdown.
-            const undraggableElementTypes = ['INPUT', 'SELECT', 'IMG'];
-            let hasSuitableAncestors = false;
-            let ancestor = element.parentElement;
-            while (ancestor) {
-                if (undraggableElementTypes.includes(ancestor.tagName)) {
-                    break;
-                }
-                if (ancestor === this.sidebarContainer) {
-                    hasSuitableAncestors = true;
-                    break;
-                }
-                ancestor = ancestor.parentElement;
-            }
-            return !undraggableElementTypes.includes(element.tagName) && hasSuitableAncestors;
-        };
-        const clickThreshold = 5;
-        // Returns whether the current (or if no current, **the last**) gesture is roughly a click.
-        // Because this can be called **after** a gesture has just ended, it should not require
-        // the gesture to be in progress.
-        const isRoughlyClick = () => {
-            return Math.hypot(lastX - startX, lastY - startY) < clickThreshold;
-        };
-        let startedDragging = false;
-        this.sidebarContainer.addEventListener('pointerdown', event => {
-            if (event.defaultPrevented || !isDraggableElement(event.target)) {
-                return;
-            }
-            if (event.isPrimary) {
-                startedDragging = false;
-                lastX = event.clientX;
-                lastY = event.clientY;
-                startX = event.clientX;
-                startY = event.clientY;
-                capturedPointerId = null;
-                pointerDown = true;
-            }
-        }, { passive: true });
+        // Set lastGestureWasRoughlyClick to `true` initially because on page load
+        // performance.now() is zero.
+        let lastGestureWasRoughlyClick = true;
         let gestureEndTimestamp = 0;
-        const onGestureEnd = (_event) => {
-            // If the pointerup/pointercancel event was for a pointer not being tracked,
-            if (!pointerDown) {
-                return;
-            }
-            gestureEndTimestamp = performance.now();
-            if (capturedPointerId !== null) {
-                this.sidebarContainer.releasePointerCapture(capturedPointerId);
-                capturedPointerId = null;
-            }
-            this.finalizeDrag();
-            pointerDown = false;
-            startedDragging = false;
-        };
-        this.sidebarContainer.onpointermove = event => {
-            if (!event.isPrimary || !pointerDown) {
-                return undefined;
-            }
-            // Mouse event and no buttons pressed? Cancel the event.
-            // This can happen if the event was canceled by a focus change (e.g. by opening a
-            // right-click menu).
-            if (event.pointerType === 'mouse' && event.buttons === 0) {
-                onGestureEnd(event);
-                return undefined;
-            }
-            // Only capture after motion -- capturing early prevents click events in Chrome.
-            if (capturedPointerId === null && !isRoughlyClick()) {
-                this.sidebarContainer.setPointerCapture(event.pointerId);
-                capturedPointerId = event.pointerId;
-            }
-            const x = event.clientX;
-            const y = event.clientY;
-            const dx = x - lastX;
-            const dy = y - lastY;
-            if (Math.abs(y - startY) > clickThreshold || startedDragging) {
-                this.handleDrag(dx, dy);
-                lastX = x;
-                lastY = y;
-                startedDragging = true;
-            }
-        };
-        this.sidebarContainer.onpointerleave = event => {
-            {
-                // Capture the pointer if it exits the container while dragging.
-                if (capturedPointerId === null && pointerDown && event.isPrimary) {
-                    this.sidebarContainer.setPointerCapture(event.pointerId);
-                    capturedPointerId = event.pointerId;
-                }
-            }
-        };
+        const dragController = makeDraggable(this.sidebarContainer, {
+            draggableChildElements: dragElements,
+            onDrag: (deltaX, deltaY) => this.handleDrag(deltaX, deltaY),
+            onDragEnd: (dragStatistics) => {
+                gestureEndTimestamp = dragStatistics.endTimestamp;
+                lastGestureWasRoughlyClick = dragStatistics.roughlyClick;
+                this.finalizeDrag();
+            },
+        });
+        this.clearDragListeners = () => dragController.removeListeners();
         this.closeButton.onclick = () => {
             const wasJustDragging = performance.now() - gestureEndTimestamp < 100;
-            const roughlyClick = isRoughlyClick();
             // Ignore the click event if it was caused by dragging the button.
-            if (wasJustDragging && roughlyClick || !wasJustDragging) {
+            if ((wasJustDragging && lastGestureWasRoughlyClick) || !wasJustDragging) {
                 this.sidebarVisible.set(false);
             }
         };
-        this.sidebarContainer.onpointerup = onGestureEnd;
-        this.sidebarContainer.onpointercancel = onGestureEnd;
     }
     /**
      * Updates the position of this menu **during** a drag. After a drag ends,

package/dist/mjs/toolbar/IconProvider.d.ts

@@ -66,6 +66,7 @@ export default class IconProvider {
     makeSaveIcon(): IconElemType;
     makeConfigureDocumentIcon(): IconElemType;
     makeOverflowIcon(): IconElemType;
+    makeHelpIcon(): IconElemType;
     /**
      * @param pathData - SVG path data (e.g. `m10,10l30,30z`)
      * @param fill - A valid CSS color (e.g. `var(--icon-color)` or `#f0f`). This can be `none`.

package/dist/mjs/toolbar/IconProvider.mjs

@@ -779,6 +779,33 @@ class IconProvider {
 			z
 		`);
     }
+    makeHelpIcon() {
+        const svg = document.createElementNS('http://www.w3.org/2000/svg', 'svg');
+        svg.innerHTML = `
+			<circle
+				style="stroke-width:1.587; stroke: var(--icon-color);"
+				fill="none"
+				cx="13.23"
+				cy="13.23"
+				r="11.9"
+			/>
+			<path
+				style="stroke-width: 3; stroke-linecap: butt; stroke: var(--icon-color);"
+				fill="none"
+				d="M 9.26,6.61 C 18.7,3.25 19.95,10.4 14.3,13.4 c -1.15,0.61 -1.32,1.32 -1.32,2.65 v 2.12"
+			/>
+			<circle
+				style="fill: var(--icon-color);"
+				cx="13"
+				cy="21.32"
+				r="1.9"
+			/>
+		`;
+        svg.setAttribute('viewBox', '0 0 26.46 26.46');
+        svg.setAttribute('width', '100');
+        svg.setAttribute('height', '100');
+        return svg;
+    }
     /**
      * @param pathData - SVG path data (e.g. `m10,10l30,30z`)
      * @param fill - A valid CSS color (e.g. `var(--icon-color)` or `#f0f`). This can be `none`.

package/dist/mjs/toolbar/localization.d.ts

@@ -1,4 +1,5 @@
-export interface ToolbarLocalization {
+import { ToolbarUtilsLocalization } from './utils/localization';
+export interface ToolbarLocalization extends ToolbarUtilsLocalization {
     fontLabel: string;
     textSize: string;
     touchPanning: string;
@@ -52,6 +53,32 @@ export interface ToolbarLocalization {
     inputStabilization: string;
     strokeAutocorrect: string;
     errorImageHasZeroSize: string;
+    describeTheImage: string;
+    penDropdown__baseHelpText: string;
+    penDropdown__colorHelpText: string;
+    penDropdown__thicknessHelpText: string;
+    penDropdown__penTypeHelpText: string;
+    penDropdown__autocorrectHelpText: string;
+    penDropdown__stabilizationHelpText: string;
+    handDropdown__baseHelpText: string;
+    handDropdown__zoomDisplayHelpText: string;
+    handDropdown__zoomInHelpText: string;
+    handDropdown__zoomOutHelpText: string;
+    handDropdown__resetViewHelpText: string;
+    handDropdown__touchPanningHelpText: string;
+    handDropdown__lockRotationHelpText: string;
+    selectionDropdown__baseHelpText: string;
+    selectionDropdown__resizeToHelpText: string;
+    selectionDropdown__deleteHelpText: string;
+    selectionDropdown__duplicateHelpText: string;
+    selectionDropdown__changeColorHelpText: string;
+    pageDropdown__baseHelpText: string;
+    pageDropdown__backgroundColorHelpText: string;
+    pageDropdown__gridCheckboxHelpText: string;
+    pageDropdown__aboutButtonHelpText: string;
+    pageDropdown__autoresizeCheckboxHelpText: string;
+    colorPickerPipetteHelpText: string;
+    colorPickerToggleHelpText: string;
     closeSidebar: (toolName: string) => string;
     dropdownShown: (toolName: string) => string;
     dropdownHidden: (toolName: string) => string;

package/dist/mjs/toolbar/localization.mjs

@@ -1,4 +1,6 @@
+import  { defaultToolbarUtilsLocalization }  from './utils/localization.mjs';
 export const defaultToolbarLocalization = {
+    ...defaultToolbarUtilsLocalization,
     pen: 'Pen',
     eraser: 'Eraser',
     select: 'Select',
@@ -51,12 +53,39 @@ export const defaultToolbarLocalization = {
     outlinedCirclePen: 'Outlined circle',
     lockRotation: 'Lock rotation',
     paste: 'Paste',
+    errorImageHasZeroSize: 'Error: Image has zero size',
+    describeTheImage: 'Image description',
+    // Help text
+    penDropdown__baseHelpText: 'This tool draws shapes or freehand lines.',
+    penDropdown__colorHelpText: 'Changes the pen\'s color',
+    penDropdown__thicknessHelpText: 'Changes the thickness of strokes drawn by the pen.',
+    penDropdown__penTypeHelpText: 'Changes the pen style.\n\nEither a “pen tip” style or “shape” can be chosen. Choosing a “pen tip” style draws freehand lines. Choosing a “shape” draws shapes.',
+    penDropdown__autocorrectHelpText: 'Converts approximate freehand lines and rectangles to perfect ones.\n\nThe pen must be held stationary at the end of a stroke to trigger a correction.',
+    penDropdown__stabilizationHelpText: 'Draws smoother strokes.\n\nThis also adds a short delay between the mouse/stylus and the stroke.',
+    handDropdown__baseHelpText: 'This tool is responsible for scrolling, rotating, and zooming the editor.',
+    handDropdown__zoomInHelpText: 'Zooms in.',
+    handDropdown__zoomOutHelpText: 'Zooms out.',
+    handDropdown__resetViewHelpText: 'Resets the zoom level to 100% and resets scroll.',
+    handDropdown__zoomDisplayHelpText: 'Shows the current zoom level. 100% shows the image at its actual size.',
+    handDropdown__touchPanningHelpText: 'When enabled, touch gestures move the image rather than select or draw.',
+    handDropdown__lockRotationHelpText: 'When enabled, prevents touch gestures from rotating the screen.',
+    selectionDropdown__baseHelpText: 'Selects content and manipulates the selection',
+    selectionDropdown__resizeToHelpText: 'Crops the drawing to the size of what\'s currently selected.\n\nIf auto-resize is enabled, it will be disabled.',
+    selectionDropdown__deleteHelpText: 'Erases selected items.',
+    selectionDropdown__duplicateHelpText: 'Makes a copy of selected items.',
+    selectionDropdown__changeColorHelpText: 'Changes the color of selected items.',
+    pageDropdown__baseHelpText: 'Controls the drawing canvas\' background color, pattern, and size.',
+    pageDropdown__backgroundColorHelpText: 'Changes the background color of the drawing canvas.',
+    pageDropdown__gridCheckboxHelpText: 'Enables/disables a background grid pattern.',
+    pageDropdown__autoresizeCheckboxHelpText: 'When checked, the page grows to fit the drawing.\n\nWhen unchecked, the page is visible and its size can be set manually.',
+    pageDropdown__aboutButtonHelpText: 'Shows version, debug, and other information.',
+    colorPickerPipetteHelpText: 'Picks a color from the screen.',
+    colorPickerToggleHelpText: 'Opens/closes the color picker.',
     closeSidebar: (toolName) => `Close sidebar for ${toolName}`,
     dropdownShown: (toolName) => `Menu for ${toolName} shown`,
     dropdownHidden: (toolName) => `Menu for ${toolName} hidden`,
     zoomLevel: (zoomPercent) => `Zoom: ${zoomPercent}%`,
     colorChangedAnnouncement: (color) => `Color changed to ${color}`,
     imageSize: (size, units) => `Image size: ${size} ${units}`,
-    errorImageHasZeroSize: 'Error: Image has zero size',
     imageLoadError: (message) => `Error loading image: ${message}`,
 };

package/dist/mjs/toolbar/utils/HelpDisplay.d.ts

@@ -0,0 +1,37 @@
+import { ToolbarContext } from '../types';
+export interface HelpRecord {
+    readonly helpText: string;
+    /**
+     * Elements that have `helpText`. Conceptually, these
+     * `HTMLElement`s form a single control (e.g. different radio
+     * buttons in a button group).
+     *
+     * The elements are all shown at once by a `HelpDisplay`.
+     */
+    readonly targetElements: HTMLElement[];
+}
+/**
+ * Creates and manages an overlay that shows help text for a set of
+ * `HTMLElement`s.
+ *
+ * @see {@link BaseWidget.fillDropdown}.
+ */
+export default class HelpDisplay {
+    #private;
+    private createOverlay;
+    private context;
+    /** Constructed internally by BaseWidget. @internal */
+    constructor(createOverlay: (htmlElement: HTMLElement) => void, context: ToolbarContext);
+    /** @internal */
+    showHelpOverlay(): void;
+    /** Marks `helpText` as associated with a single `targetElement`. */
+    registerTextHelpForElement(targetElement: HTMLElement, helpText: string): void;
+    /** Marks `helpText` as associated with all elements in `targetElements`. */
+    registerTextHelpForElements(targetElements: HTMLElement[], helpText: string): void;
+    /** Returns true if any help text has been registered. */
+    hasHelpText(): boolean;
+    /**
+     * Creates and returns a button that toggles the help display.
+     */
+    createToggleButton(): HTMLElement;
+}