fabric 5.3.0 → 6.0.0-beta1

package/dist/src/shapes/IText/IText.d.ts

@@ -0,0 +1,322 @@
+import { ITextEvents } from './ITextBehavior';
+import { ITextClickBehavior } from './ITextClickBehavior';
+import { AssertKeys, TFiller } from '../../typedefs';
+type CursorBoundaries = {
+    left: number;
+    top: number;
+    leftOffset: number;
+    topOffset: number;
+};
+/**
+ * @fires changed
+ * @fires selection:changed
+ * @fires editing:entered
+ * @fires editing:exited
+ * @fires dragstart
+ * @fires drag drag event firing on the drag source
+ * @fires dragend
+ * @fires copy
+ * @fires cut
+ * @fires paste
+ *
+ * #### Supported key combinations
+ * ```
+ *   Move cursor:                    left, right, up, down
+ *   Select character:               shift + left, shift + right
+ *   Select text vertically:         shift + up, shift + down
+ *   Move cursor by word:            alt + left, alt + right
+ *   Select words:                   shift + alt + left, shift + alt + right
+ *   Move cursor to line start/end:  cmd + left, cmd + right or home, end
+ *   Select till start/end of line:  cmd + shift + left, cmd + shift + right or shift + home, shift + end
+ *   Jump to start/end of text:      cmd + up, cmd + down
+ *   Select till start/end of text:  cmd + shift + up, cmd + shift + down or shift + pgUp, shift + pgDown
+ *   Delete character:               backspace
+ *   Delete word:                    alt + backspace
+ *   Delete line:                    cmd + backspace
+ *   Forward delete:                 delete
+ *   Copy text:                      ctrl/cmd + c
+ *   Paste text:                     ctrl/cmd + v
+ *   Cut text:                       ctrl/cmd + x
+ *   Select entire text:             ctrl/cmd + a
+ *   Quit editing                    tab or esc
+ * ```
+ *
+ * #### Supported mouse/touch combination
+ * ```
+ *   Position cursor:                click/touch
+ *   Create selection:               click/touch & drag
+ *   Create selection:               click & shift + click
+ *   Select word:                    double click
+ *   Select line:                    triple click
+ * ```
+ */
+export declare class IText<EventSpec extends ITextEvents = ITextEvents> extends ITextClickBehavior<EventSpec> {
+    /**
+     * Index where text selection starts (or where cursor is when there is no selection)
+     * @type Number
+     * @default
+     */
+    selectionStart: number;
+    /**
+     * Index where text selection ends
+     * @type Number
+     * @default
+     */
+    selectionEnd: number;
+    compositionStart: number;
+    compositionEnd: number;
+    /**
+     * Color of text selection
+     * @type String
+     * @default
+     */
+    selectionColor: string;
+    /**
+     * Indicates whether text is in editing mode
+     * @type Boolean
+     * @default
+     */
+    isEditing: boolean;
+    /**
+     * Indicates whether a text can be edited
+     * @type Boolean
+     * @default
+     */
+    editable: boolean;
+    /**
+     * Border color of text object while it's in editing mode
+     * @type String
+     * @default
+     */
+    editingBorderColor: string;
+    /**
+     * Width of cursor (in px)
+     * @type Number
+     * @default
+     */
+    cursorWidth: number;
+    /**
+     * Color of text cursor color in editing mode.
+     * if not set (default) will take color from the text.
+     * if set to a color value that fabric can understand, it will
+     * be used instead of the color of the text at the current position.
+     * @type String
+     * @default
+     */
+    cursorColor: string;
+    /**
+     * Delay between cursor blink (in ms)
+     * @type Number
+     * @default
+     */
+    cursorDelay: number;
+    /**
+     * Duration of cursor fade in (in ms)
+     * @type Number
+     * @default
+     */
+    cursorDuration: number;
+    compositionColor: string;
+    /**
+     * Indicates whether internal text char widths can be cached
+     * @type Boolean
+     * @default
+     */
+    caching: boolean;
+    /**
+  
+     * Constructor
+     * @param {String} text Text string
+     * @param {Object} [options] Options object
+     */
+    constructor(text: string, options: object);
+    /**
+     * While editing handle differently
+     * @private
+     * @param {string} key
+     * @param {*} value
+     */
+    _set(key: string, value: any): this;
+    /**
+     * Sets selection start (left boundary of a selection)
+     * @param {Number} index Index to set selection start to
+     */
+    setSelectionStart(index: number): void;
+    /**
+     * Sets selection end (right boundary of a selection)
+     * @param {Number} index Index to set selection end to
+     */
+    setSelectionEnd(index: number): void;
+    /**
+     * @private
+     * @param {String} property 'selectionStart' or 'selectionEnd'
+     * @param {Number} index new position of property
+     */
+    protected _updateAndFire(property: 'selectionStart' | 'selectionEnd', index: number): void;
+    /**
+     * Fires the even of selection changed
+     * @private
+     */
+    _fireSelectionChanged(): void;
+    /**
+     * Initialize text dimensions. Render all text on given context
+     * or on a offscreen canvas to get the text width with measureText.
+     * Updates this.width and this.height with the proper values.
+     * Does not return dimensions.
+     * @private
+     */
+    initDimensions(): void;
+    /**
+     * Gets style of a current selection/cursor (at the start position)
+     * if startIndex or endIndex are not provided, selectionStart or selectionEnd will be used.
+     * @param {Number} startIndex Start index to get styles at
+     * @param {Number} endIndex End index to get styles at, if not specified selectionEnd or startIndex + 1
+     * @param {Boolean} [complete] get full style or not
+     * @return {Array} styles an array with one, zero or more Style objects
+     */
+    getSelectionStyles(startIndex?: number, endIndex?: number, complete?: boolean): import("../Text/StyledText").TextStyleDeclaration[];
+    /**
+     * Sets style of a current selection, if no selection exist, do not set anything.
+     * @param {Object} [styles] Styles object
+     * @param {Number} [startIndex] Start index to get styles at
+     * @param {Number} [endIndex] End index to get styles at, if not specified selectionEnd or startIndex + 1
+     */
+    setSelectionStyles(styles: object, startIndex?: number, endIndex?: number): void;
+    /**
+     * Returns 2d representation (lineIndex and charIndex) of cursor (or selection start)
+     * @param {Number} [selectionStart] Optional index. When not given, current selectionStart is used.
+     * @param {Boolean} [skipWrapping] consider the location for unwrapped lines. useful to manage styles.
+     */
+    get2DCursorLocation(selectionStart?: number, skipWrapping?: boolean): {
+        lineIndex: number;
+        charIndex: number;
+    };
+    /**
+     * @private
+     * @param {CanvasRenderingContext2D} ctx Context to render on
+     */
+    render(ctx: CanvasRenderingContext2D): void;
+    /**
+     * @override block cursor/selection logic while rendering the exported canvas
+     * @todo this workaround should be replaced with a more robust solution
+     */
+    toCanvasElement(options?: any): HTMLCanvasElement;
+    /**
+     * Renders cursor or selection (depending on what exists)
+     * it does on the contextTop. If contextTop is not available, do nothing.
+     */
+    renderCursorOrSelection(): void;
+    /**
+     * Returns cursor boundaries (left, top, leftOffset, topOffset)
+     * left/top are left/top of entire text box
+     * leftOffset/topOffset are offset from that left/top point of a text box
+     * @private
+     * @param {number} [index] index from start
+     * @param {boolean} [skipCaching]
+     */
+    _getCursorBoundaries(index?: number, skipCaching?: boolean): CursorBoundaries;
+    /**
+     * Caches and returns cursor left/top offset relative to instance's center point
+     * @private
+     * @param {number} index index from start
+     * @param {boolean} [skipCaching]
+     */
+    _getCursorBoundariesOffsets(index: number, skipCaching?: boolean): {
+        left: number;
+        top: number;
+    };
+    /**
+     * Calculates cursor left/top offset relative to instance's center point
+     * @private
+     * @param {number} index index from start
+     */
+    __getCursorBoundariesOffsets(index: number): {
+        top: number;
+        left: number;
+    };
+    /**
+     * Renders cursor on context Top, outside the animation cycle, on request
+     * Used for the drag/drop effect.
+     * If contextTop is not available, do nothing.
+     */
+    renderCursorAt(selectionStart: number): void;
+    /**
+     * Renders cursor
+     * @param {Object} boundaries
+     * @param {CanvasRenderingContext2D} ctx transformed context to draw on
+     */
+    renderCursor(ctx: CanvasRenderingContext2D, boundaries: CursorBoundaries): void;
+    _renderCursor(ctx: CanvasRenderingContext2D, boundaries: CursorBoundaries, selectionStart: number): void;
+    /**
+     * Renders text selection
+     * @param {Object} boundaries Object with left/top/leftOffset/topOffset
+     * @param {CanvasRenderingContext2D} ctx transformed context to draw on
+     */
+    renderSelection(ctx: CanvasRenderingContext2D, boundaries: CursorBoundaries): void;
+    /**
+     * Renders drag start text selection
+     */
+    renderDragSourceEffect(this: AssertKeys<this, 'canvas'>): void;
+    renderDropTargetEffect(e: DragEvent): void;
+    /**
+     * Renders text selection
+     * @private
+     * @param {{ selectionStart: number, selectionEnd: number }} selection
+     * @param {Object} boundaries Object with left/top/leftOffset/topOffset
+     * @param {CanvasRenderingContext2D} ctx transformed context to draw on
+     */
+    _renderSelection(ctx: CanvasRenderingContext2D, selection: {
+        selectionStart: number;
+        selectionEnd: number;
+    }, boundaries: CursorBoundaries): void;
+    /**
+     * High level function to know the height of the cursor.
+     * the currentChar is the one that precedes the cursor
+     * Returns fontSize of char at the current cursor
+     * Unused from the library, is for the end user
+     * @return {Number} Character font size
+     */
+    getCurrentCharFontSize(): number;
+    /**
+     * High level function to know the color of the cursor.
+     * the currentChar is the one that precedes the cursor
+     * Returns color (fill) of char at the current cursor
+     * if the text object has a pattern or gradient for filler, it will return that.
+     * Unused by the library, is for the end user
+     * @return {String | TFiller} Character color (fill)
+     */
+    getCurrentCharColor(): string | TFiller;
+    /**
+     * Returns the cursor position for the getCurrent.. functions
+     * @private
+     */
+    _getCurrentCharIndex(): {
+        l: number;
+        c: number;
+    };
+    dispose(): void;
+}
+export declare const iTextDefaultValues: {
+    type: string;
+    selectionStart: number;
+    selectionEnd: number;
+    selectionColor: string;
+    isEditing: boolean;
+    editable: boolean;
+    editingBorderColor: string;
+    cursorWidth: number;
+    cursorColor: string;
+    cursorDelay: number;
+    cursorDuration: number;
+    caching: boolean;
+    hiddenTextareaContainer: null;
+    _selectionDirection: null;
+    _reSpace: RegExp;
+    inCompositionMode: boolean;
+    keysMap: import("./constants").TKeyMapIText;
+    keysMapRtl: import("./constants").TKeyMapIText;
+    ctrlKeysMapDown: import("./constants").TKeyMapIText;
+    ctrlKeysMapUp: import("./constants").TKeyMapIText;
+};
+export {};
+//# sourceMappingURL=IText.d.ts.map

package/dist/src/shapes/IText/ITextBehavior.d.ts

@@ -0,0 +1,285 @@
+import { ObjectEvents, TPointerEvent, TPointerEventInfo } from '../../EventTypeDefs';
+import type { FabricObject } from '../Object/Object';
+import { Text } from '../Text/Text';
+import { TOnAnimationChangeCallback } from '../../util/animation/types';
+import type { ValueAnimation } from '../../util/animation/ValueAnimation';
+import { TextStyleDeclaration } from '../Text/StyledText';
+export type ITextEvents = ObjectEvents & {
+    'selection:changed': never;
+    changed: never | {
+        index: number;
+        action: string;
+    };
+    tripleclick: TPointerEventInfo;
+    'editing:entered': never | {
+        e: TPointerEvent;
+    };
+    'editing:exited': never;
+};
+export declare abstract class ITextBehavior<EventSpec extends ITextEvents = ITextEvents> extends Text<EventSpec> {
+    abstract isEditing: boolean;
+    abstract cursorDelay: number;
+    abstract selectionStart: number;
+    abstract selectionEnd: number;
+    abstract cursorDuration: number;
+    abstract editable: boolean;
+    abstract editingBorderColor: string;
+    abstract compositionStart: number;
+    abstract compositionEnd: number;
+    abstract hiddenTextarea: HTMLTextAreaElement | null;
+    /**
+     * Helps determining when the text is in composition, so that the cursor
+     * rendering is altered.
+     */
+    protected inCompositionMode: boolean;
+    protected _reSpace: RegExp;
+    private _currentTickState?;
+    private _currentTickCompleteState?;
+    protected _currentCursorOpacity: number;
+    private _textBeforeEdit;
+    protected __selectionStartOnMouseDown: number;
+    protected selected: boolean;
+    protected cursorOffsetCache: {
+        left?: number;
+        top?: number;
+    };
+    protected _savedProps?: {
+        hasControls: boolean;
+        borderColor: string;
+        lockMovementX: boolean;
+        lockMovementY: boolean;
+        selectable: boolean;
+        hoverCursor: CSSStyleDeclaration['cursor'] | null;
+        defaultCursor?: CSSStyleDeclaration['cursor'];
+        moveCursor?: CSSStyleDeclaration['cursor'];
+    };
+    protected _selectionDirection: 'left' | 'right' | null;
+    abstract initHiddenTextarea(): void;
+    abstract _fireSelectionChanged(): void;
+    abstract renderCursorOrSelection(): void;
+    abstract getSelectionStartFromPointer(e: TPointerEvent): number;
+    abstract _getCursorBoundaries(index: number, skipCaching?: boolean): {
+        left: number;
+        top: number;
+        leftOffset: number;
+        topOffset: number;
+    };
+    /**
+     * Initializes all the interactive behavior of IText
+     */
+    initBehavior(): void;
+    onDeselect(options?: {
+        e?: TPointerEvent;
+        object?: FabricObject;
+    }): boolean;
+    /**
+     * @private
+     */
+    _animateCursor({ toValue, duration, delay, onComplete, }: {
+        toValue: number;
+        duration: number;
+        delay?: number;
+        onComplete?: TOnAnimationChangeCallback<number, void>;
+    }): ValueAnimation;
+    private _tick;
+    private _onTickComplete;
+    /**
+     * Initializes delayed cursor
+     */
+    initDelayedCursor(restart?: boolean): void;
+    /**
+     * Aborts cursor animation, clears all timeouts and clear textarea context if necessary
+     */
+    abortCursorAnimation(): void;
+    restartCursorIfNeeded(): void;
+    /**
+     * Selects entire text
+     */
+    selectAll(): this;
+    /**
+     * Returns selected text
+     * @return {String}
+     */
+    getSelectedText(): string;
+    /**
+     * Find new selection index representing start of current word according to current selection index
+     * @param {Number} startFrom Current selection index
+     * @return {Number} New selection index
+     */
+    findWordBoundaryLeft(startFrom: number): number;
+    /**
+     * Find new selection index representing end of current word according to current selection index
+     * @param {Number} startFrom Current selection index
+     * @return {Number} New selection index
+     */
+    findWordBoundaryRight(startFrom: number): number;
+    /**
+     * Find new selection index representing start of current line according to current selection index
+     * @param {Number} startFrom Current selection index
+     * @return {Number} New selection index
+     */
+    findLineBoundaryLeft(startFrom: number): number;
+    /**
+     * Find new selection index representing end of current line according to current selection index
+     * @param {Number} startFrom Current selection index
+     * @return {Number} New selection index
+     */
+    findLineBoundaryRight(startFrom: number): number;
+    /**
+     * Finds index corresponding to beginning or end of a word
+     * @param {Number} selectionStart Index of a character
+     * @param {Number} direction 1 or -1
+     * @return {Number} Index of the beginning or end of a word
+     */
+    searchWordBoundary(selectionStart: number, direction: number): number;
+    /**
+     * Selects a word based on the index
+     * @param {Number} selectionStart Index of a character
+     */
+    selectWord(selectionStart: number): void;
+    /**
+     * Selects a line based on the index
+     * @param {Number} selectionStart Index of a character
+     */
+    selectLine(selectionStart: number): this;
+    /**
+     * Enters editing state
+     */
+    enterEditing(e: TPointerEvent): void;
+    /**
+     * called by {@link canvas#textEditingManager}
+     */
+    updateSelectionOnMouseMove(e: TPointerEvent): void;
+    /**
+     * @private
+     */
+    _setEditingProps(): void;
+    /**
+     * convert from textarea to grapheme indexes
+     */
+    fromStringToGraphemeSelection(start: number, end: number, text: string): {
+        selectionStart: number;
+        selectionEnd: number;
+    };
+    /**
+     * convert from fabric to textarea values
+     */
+    fromGraphemeToStringSelection(start: number, end: number, graphemes: string[]): {
+        selectionStart: number;
+        selectionEnd: number;
+    };
+    /**
+     * @private
+     */
+    _updateTextarea(): void;
+    /**
+     * @private
+     */
+    updateFromTextArea(): void;
+    /**
+     * @private
+     */
+    updateTextareaPosition(): void;
+    /**
+     * @private
+     * @return {Object} style contains style for hiddenTextarea
+     */
+    _calcTextareaPosition(): {
+        left: string;
+        top: string;
+        fontSize?: undefined;
+        charHeight?: undefined;
+    } | {
+        left: string;
+        top: string;
+        fontSize: string;
+        charHeight: number;
+    };
+    /**
+     * @private
+     */
+    _saveEditingProps(): void;
+    /**
+     * @private
+     */
+    _restoreEditingProps(): void;
+    /**
+     * runs the actual logic that exits from editing state, see {@link exitEditing}
+     */
+    protected _exitEditing(): void;
+    /**
+     * Exits from editing state and fires relevant events
+     */
+    exitEditing(): this;
+    /**
+     * @private
+     */
+    _removeExtraneousStyles(): void;
+    /**
+     * remove and reflow a style block from start to end.
+     * @param {Number} start linear start position for removal (included in removal)
+     * @param {Number} end linear end position for removal ( excluded from removal )
+     */
+    removeStyleFromTo(start: number, end: number): void;
+    /**
+     * Shifts line styles up or down
+     * @param {Number} lineIndex Index of a line
+     * @param {Number} offset Can any number?
+     */
+    shiftLineStyles(lineIndex: number, offset: number): void;
+    /**
+     * Handle insertion of more consecutive style lines for when one or more
+     * newlines gets added to the text. Since current style needs to be shifted
+     * first we shift the current style of the number lines needed, then we add
+     * new lines from the last to the first.
+     * @param {Number} lineIndex Index of a line
+     * @param {Number} charIndex Index of a char
+     * @param {Number} qty number of lines to add
+     * @param {Array} copiedStyle Array of objects styles
+     */
+    insertNewlineStyleObject(lineIndex: number, charIndex: number, qty: number, copiedStyle?: {
+        [index: number]: TextStyleDeclaration;
+    }): void;
+    /**
+     * Inserts style object for a given line/char index
+     * @param {Number} lineIndex Index of a line
+     * @param {Number} charIndex Index of a char
+     * @param {Number} quantity number Style object to insert, if given
+     * @param {Array} copiedStyle array of style objects
+     */
+    insertCharStyleObject(lineIndex: number, charIndex: number, quantity: number, copiedStyle?: TextStyleDeclaration[]): void;
+    /**
+     * Inserts style object(s)
+     * @param {Array} insertedText Characters at the location where style is inserted
+     * @param {Number} start cursor index for inserting style
+     * @param {Array} [copiedStyle] array of style objects to insert.
+     */
+    insertNewStyleBlock(insertedText: string[], start: number, copiedStyle?: TextStyleDeclaration[]): void;
+    /**
+     * Removes characters from start/end
+     * start/end ar per grapheme position in _text array.
+     *
+     * @param {Number} start
+     * @param {Number} end default to start + 1
+     */
+    removeChars(start: number, end: number): void;
+    /**
+     * insert characters at start position, before start position.
+     * start  equal 1 it means the text get inserted between actual grapheme 0 and 1
+     * if style array is provided, it must be as the same length of text in graphemes
+     * if end is provided and is bigger than start, old text is replaced.
+     * start/end ar per grapheme position in _text array.
+     *
+     * @param {String} text text to insert
+     * @param {Array} style array of style objects
+     * @param {Number} start
+     * @param {Number} end default to start + 1
+     */
+    insertChars(text: string, style: TextStyleDeclaration[] | undefined, start: number, end?: number): void;
+    /**
+     * Set the selectionStart and selectionEnd according to the new position of cursor
+     * mimic the key - mouse navigation when shift is pressed.
+     */
+    setSelectionStartEndWithShift(start: number, end: number, newSelection: number): void;
+}
+//# sourceMappingURL=ITextBehavior.d.ts.map

package/dist/src/shapes/IText/ITextClickBehavior.d.ts

@@ -0,0 +1,81 @@
+import type { TPointerEvent, TPointerEventInfo } from '../../EventTypeDefs';
+import { IPoint, Point } from '../../Point';
+import type { DragMethods } from '../Object/InteractiveObject';
+import { DraggableTextDelegate } from './DraggableTextDelegate';
+import { ITextEvents } from './ITextBehavior';
+import { ITextKeyBehavior } from './ITextKeyBehavior';
+export declare abstract class ITextClickBehavior<EventSpec extends ITextEvents = ITextEvents> extends ITextKeyBehavior<EventSpec> implements DragMethods {
+    private __lastSelected;
+    private __lastClickTime;
+    private __lastLastClickTime;
+    private __lastPointer;
+    private __newClickTime;
+    protected draggableTextDelegate: DraggableTextDelegate;
+    initBehavior(): void;
+    shouldStartDragging(): boolean;
+    /**
+     * @public override this method to control whether instance should/shouldn't become a drag source, @see also {@link DraggableTextDelegate#isActive}
+     * @returns {boolean} should handle event
+     */
+    onDragStart(e: DragEvent): boolean;
+    /**
+     * @public override this method to control whether instance should/shouldn't become a drop target
+     */
+    canDrop(e: DragEvent): boolean;
+    /**
+     * Default event handler to simulate triple click
+     * @private
+     */
+    onMouseDown(options: TPointerEventInfo): void;
+    isTripleClick(newPointer: IPoint): boolean;
+    /**
+     * Default handler for double click, select a word
+     */
+    doubleClickHandler(options: TPointerEventInfo): void;
+    /**
+     * Default handler for triple click, select a line
+     */
+    tripleClickHandler(options: TPointerEventInfo): void;
+    /**
+     * Default event handler for the basic functionalities needed on _mouseDown
+     * can be overridden to do something different.
+     * Scope of this implementation is: find the click position, set selectionStart
+     * find selectionEnd, initialize the drawing of either cursor or selection area
+     * initializing a mousedDown on a text area will cancel fabricjs knowledge of
+     * current compositionMode. It will be set to false.
+     */
+    _mouseDownHandler({ e }: TPointerEventInfo): void;
+    /**
+     * Default event handler for the basic functionalities needed on mousedown:before
+     * can be overridden to do something different.
+     * Scope of this implementation is: verify the object is already selected when mousing down
+     */
+    _mouseDownHandlerBefore({ e }: TPointerEventInfo): void;
+    /**
+     * standard handler for mouse up, overridable
+     * @private
+     */
+    mouseUpHandler({ e, transform, button }: TPointerEventInfo): void;
+    /**
+     * Changes cursor location in a text depending on passed pointer (x/y) object
+     * @param {TPointerEvent} e Event object
+     */
+    setCursorByClick(e: TPointerEvent): void;
+    /**
+     * Returns coordinates of a pointer relative to object's top left corner in object's plane
+     * @param {Point} [pointer] Pointer to operate upon
+     * @return {Point} Coordinates of a pointer (x, y)
+     */
+    getLocalPointer(pointer: Point): Point;
+    /**
+     * Returns index of a character corresponding to where an object was clicked
+     * @param {TPointerEvent} e Event object
+     * @return {Number} Index of a character
+     */
+    getSelectionStartFromPointer(e: TPointerEvent): number;
+    /**
+     * @private
+     */
+    _getNewSelectionStartFromOffset(mouseOffset: IPoint, prevWidth: number, width: number, index: number, jlen: number): number;
+}
+//# sourceMappingURL=ITextClickBehavior.d.ts.map