🧐 Breaking changes for fabric 6.0

asturur commented 2 years ago

b.0.0-beta16

This list is in progress and is meant to be an easy go to place to add things and find them when the time comes to write a document on what has changed. This will be a list of descriptive items, extended as needed to capture behavior changes. Apart from what is described here MANY bugs have been fixed in the process.

Generic concepts

Imports we moved from import { fabric } from 'fabric' to import { Canvas, Rect, util } from 'fabric' or import * as fabric from 'fabric'. To avoid packaging issues node has its own entrypoint import { StaticCanvas } from 'fabric/node'. This means there is no fabric namespace/object anymore.
- Introduced classRegistry to bridge the absence of a namespace
- Introduced the env concept, getEnv to allow node/browser specific values/logic. That has made importing fabric in SSR possible and will allow offscreen support in the future.
- renamed the following #9172:
- fabric.Object => FabricObject
- fabric.Text => FabricText
- fabric.Image => FabricImage
- Node's registerFont has been removed, use registerFont exposed by node canvas
method chaining is now deprecated, don't use it anymore. Not all methods were chainable, and chaining seems to offer limited advantages ( maybe saving 1-2 bytes in the code you write when minified? unsure what else ). Just for consistency sake and to be free to start returning useful information from some methods we will stop using it. We didn't remove it from everywhere so that there isn't unnecessary breakage, but you should consider that unsafe to use, since will break entirely on the next major release after 6.0 ( add detailed list of where has been removed so far )
Callbacks are mostly gone, all of the functions that took a callback now return a Promise, this on top of being breaking slightly alter code behavior when is fixed. Before sync code would execute the callback synchronously, now is chained to however the browser handle the promise ( not sure if it goes in the event loop and under which circumstances ). https://github.com/fabricjs/fabric.js/issues/3684
TS: The code base is typed! If you used @types/fabric you should uninstall it
Prototype Mutation: Fabric has moved to native classes. No more createClass or object.util.extend. You can still mutate the prototype, however, properties do not exist on the prototype in native classes. Look into getDefaults instead.
scene vs. viewport We introduced these concepts to describe the rendering/view planes as follows: The viewer is viewing the scene (what is rendered/"playing") from the viewport. The scene was considered is the past as the absolute plane whereas the viewport wasn't #9175. Normally geometry calculations occur in the scene with the exception of padding which is a viewport scalar.
- All events have a scenePoint and viewportPoint properties replacing the deprecated and confusing absolutePointer and pointer properties. Brushes are still in need of this change.
- dep Canvas#getPointer in favor of getScenePoint or getViewportPoint
- Using viewportTransform is rather confusing with this change (especially with sendPointToPlane etc.) perhaps be renaming to sceneTransform is the correct migration path in the future.
React Compatibility:
- Ensure proper disposal in useEffect, especially with React 18. Refer to this hook for guidance.
- Async Disposal: Handle async nature of dispose method. The asynchronous disposal of Canvas and StaticCanvas safeguards an edge case in which dispose is called while rendering is still in progress. This should burden your react app.
- DOM Mutation: Fabric modifies the DOM and cleans up after itself as long as Canvas#dispose is called

Collection

not available as a standard object as fabric.Collection any longer, was never meant to, it was a constrain of the previous build system ( we had no imports or require or bundling before ).
insertAt method signature changed from insertAt(object, index) to insertAt(index, ...objects)
Collection now owns the stack too, methods were renamed to accommodate Group:
- sendObjectToBack ~~sendToBack~~
- bringObjectToFront ~~bringToFront~~
- sendObjectBackwards ~~sendBackwards~~
- bringObjectForward ~~bringForward~~
- moveObjectTo ~~moveTo~~
Support to stack operations with active selection is gone

Canvas and StaticCanvas

Canvas.dispose and StaticCanvas.dispose are now async In order to handle some concurrency issue with requestAnimationFrame, dispose is now checking and waiting for any uncancellable render to finish. This could have some side effects, especially in complex environments with UI frameworks and hot reload of code.
trying to initialize a canvas that has already been initialized #7776 is not breaking, it saves the dev from a silent breakage that they weren't aware of
removed canvas.straightenObject wasn't really useful.
changed cloneWithoutData , now it does not clone backgrounds.
canvas.clone now correctly return either a canvas or staticCanvas
drawClipPathOnCanvas signature changed: now accepts the clipPath as a second argument instead of rechecking its existence
getCenter renamed to getCenterPoint #7699
add returns the length of the array of objects after adding, like Array#push
remove returns an array with the removed objects inside
insertAt method signature changed (refer to the Collection section)
removed sendToBack, bringToFront, sendBackward, moveTo, bringForward ( and gained similar methods from collection (refer to the Collection section)
Canvas#freeDrawingBrush is not set by default
scene vs. viewport changes
- dep getPointer in favor of getScenePoint or getViewportPoint
- rm _normalizePointer, restorePointerVpt
rm interactive flag, use instance of Canvas instead
rm setBackgroundColor, setBackgroundImage, setOverlayColor, setOverlayImage: assign the property directly and render the canvas

Object

BREAKING Coords system improvements:
- removed lineCoords
- aCoords should be treated as protected , if you need the scene corners of an object use getCoords
- fixed coords to respect grouping and nesting, see the Group section
- removed absolute, calculate from geometry methods signatures (all listed methods operate in the scene):
  - getCoords
  - intersectsWithRect
  - intersectsWithObject
  - isContainedWithinObject
  - isContainedWithinRect
  - getBoundingRect
  - containsPoint changed signature entirely and fixed
- getRelativeXY/setRelativeXY to get/set the coordinate in the parent plane, getXY/setXY to get/set the coordinate in the scene plane
- adjustPosition is gone. It took a parameter only, was internally unused, didn't take care of internal edge cases setPositionByOrigin is more flexible
- rm _setOriginToCenter and _resetOrigin #9179
- Control coords (oCoords) are calculated only if the object has a canvas ref
type has become a static field and should be used only for serialization with classRegistry. There is still a deprecated getter on the object for compatibility reasons. Avoid using it.
Object looses the stack methods, instead of guessing which was the stack we refer to when we move forward/backward we do that from the stack itself #8461, see the Collection section
stateful functionality is deprecated, is officially removed, but is still reacheable. Don't use it. Comparing large set of propeties to detect a change doesn't really play well neither with performance nor with edge cases. stateful and statefulCache are removed. stateful was used to fire an object modified every render cycle in which a change in state properties was determiend. All the events that can modify an object already fire an object:modified event, and the user has no ability to change colors or state outside developer written code, so there is no really need for event firing here. statefulCache was an experiment and the suggestion to use set(property, value) replaced it since long. FabricJS internally still use some stateful logic for now, but the intention is to get rid of it.
methods like center, centerH, centerV, viewportCenter are gone. Those were aliases for the canvas methods, use them instead.
animate changed to adapt to animation changes
The controls object is not shared between instances - it is not on the prototype as all class fields
BREAKING: Object#getObjectScaling, Object#getTotalObjectScaling now returns Point instead of {scaleX,scaleY} #7710

Text

see Text styles under the Serialization section
rename data-fabric-hiddentextarea to data-fabric with value textarea, if you were using hasAttribute('data-fabric-hiddentextarea') now you have to use getAttribute('data-fabric') and then check for equality with textarea or change your cssSelector accordingly.
_getStyleDeclaration returns an empty object instead of undefined when style is not set.
controls can be used in editing mode

Polyline Polygon Path

_setPositionDimensions (considered private in the past), has been renamed to setDimensions. The logic with which Polyline based object calculate the size is changed. There wasn't an api in 5.x to change the size, but devs needed to do it anyway and the alternative was to create a new object. Is not called setPositionAndDimensions because the logic to correcly change size while keeping a visual correct position is not there yet and maybe it won't.
exposed long desired poly controls createPolyControls

Group

complete rewrite described in #7670
CONCEPT: Group rewrite exposes a change in concept - strict object tree. An object can belong to one parent.
exposed the parent property on FabricObject alongside group to allow an object to return to its parent after being deselected from an active selection.
addWithUpdate is gone, now add does what it has to do.
LayoutManager has been introduced to handle group layout #9152. By default it will be fit-content, meaning the group will fit around its objects, updating when objects are added/removed/modified.

Controls

expose shouldActivate for ease of use #8934 #9374
no longer shared, they are a class field

Serialization

Text#styles is now exported differently. This is BREAKING only if you are handling the style object post export The default object we exported was large most of the time, with tons of empty keys and verbosity. It seems reasonable to think that most of the time text is styled in some chunk of text with coherent different styles ( eg: a red word in a black text or some words underlined and some not more than a rainbow of different stylings per object ) for that reason we changed the approach of serialization to an array with start and end index for the style. We didn't apply that to actual runtime code because we were unsure of performance, so at least for version 6, styles at runtime are going to be the same. It is highly recommended to not fiddle with the style object directly and to treat it as internal, using the public facing methods to apply changes. https://github.com/fabricjs/fabric.js/pull/8006
populateWithProperties => pick populate with properties was used internally to add the extra options to exported objects. Between spread operator and new syntax, a generic pick approach seemed more correct.
toJSON is not an alias of toObject. This was a long standing bug, but also a breaking change. toJSON never accepted additional properties and will give you only the default object export. toJSON is meant for JSON#stringify interoperability and is not meant to be used in your code base directly. reference #8111
classRegistry => register your subclasses to use them during serialization
NUM_FRACTION_DIGIT moved to config and incremented from 2 to 4

Brushes

PatternBrush: removed the getPatternSrcFunction. Wasn't working anymore since the refactor of Pattern and also a super weird practice.

Animation

animation util does not accept anymore the += or -= syntax for changes, nor accept the byValue option. You can specify an animation only by startValue and endValue.
Every animation returns a class with a cancel method to cancel the animation.
Animation callback onChange and onComplete will fire for every animation generated by set of properties. This change is necessary because if we assign the callbacks to only one animation, in case that animation will be cancelled, the other ones won't have any registered callback.

Utils

makeBoundingBoxFromPoints signature change. The transformation is not supported anymore and requires real points
removal of all the array utils ( min, max, find those are well covered by es6 now and also is out of fabric scope to provide generic data manipulation utils )
some utils are considered internal and not exposed anymore ( TODO add list )
clone and extend have been removed. Those were used in all examples unfortunately so the community has likely adopted them, consider migrating to a well known common library for those functionalities ( lodash, underscore ... ). Avoid using such utilities on classes.
makeElementSelectable and makeElementUnselectable are removed. Those were needed internally and one of them is still used internally, but is not a fabricJS core functionality and not part of the api anymore.
exposed sendObjectToPlane, sendPointToPlane, sendVectorToPlane to ease common usages of linear algebra. Check them out, you will benefit from it.
exposed more vector utils

Misc

Observable now returns a disposer making it easier to use and the off method redundant #7994
Point methods #7716 #7709
Eraser has been extracted to https://github.com/ShaMan123/erase2d
Touch gestures are not yet migrated/officially supported - use a lib for that for now
Build pipeline (rollup)
new testing frameworks (jest, playwright)

Sara-Sultan commented 1 year ago

@ShaMan123 I also wonder how to check target from Event on object as it is unkown type canvas.on('object:scaled', e=>{ let target = e.target; }

Error Msg: Property 'target' does not exist on type 'unkown'.

ShaMan123 commented 1 year ago

That event is deprecated. object:modified instead and check for the action or actionName if you need

ShaMan123 commented 1 year ago

@bladerunner2020 please post your good comment in the relative thread #8899 and remove from this one

jiayihu commented 1 year ago

A list of a few breaking changes not listed yet (I'll update this list as we migrate to fabric v6):

The type property of objects is not overridable anymore because it's only a getter
Declaration merging of the TS types changed from namespace to module. This also means that fabric TS types need to be imported now, cannot rely on global fabric.Object type for instance

abdussami-tayyab commented 1 year ago

How can we initialize a Canvas in React and ensure that the fabric.Canvas object is available in methods outside useEffect as well? Sorry I struggle with that, and would like some help there as this version provides interaction with group which I very importantly need.

Thanks for all the efforts you guys are putting and good luck!

bladerunner2020 commented 1 year ago

How can we initialize a Canvas in React...

Though it's not clear what do you mean by 'outside useEffect', I would suggest to look at the article, that helped us a lot to setup React-wrapper for fabric: https://binarapps.com/integrate-fabric-js-canvas-drawing-library-with-react-app-via-uncontrolled-component/

ShaMan123 commented 1 year ago

take a look at https://github.com/fabricjs/fabric.js/blob/master/.codesandbox/templates/next/pages/index.tsx

vinkovsky commented 1 year ago

How can we initialize a Canvas in React and ensure that the fabric.Canvas object is available in methods outside useEffect as well? Sorry I struggle with that, and would like some help there as this version provides interaction with group which I very importantly need.

Thanks for all the efforts you guys are putting and good luck!

You can wrap your canvas component with React Context

abdussami-tayyab commented 1 year ago

Thank you @vinkovsky @ShaMan123 and @bladerunner2020 .

Pardon my lack of knowledge working with ReactJS, I followed @ShaMan123 's link (even though it's Typescript and I would like JS) and got it working somehow. However, @bladerunner2020 , your solution causes an issue of canvas already initialised already mentioned in #8899 .

Happy to help provide more info if it helps.

asturur commented 1 year ago

added breaking changes from #8930

hanna-becker commented 1 year ago

Are there any breaking changes with free drawing? I'm migrating my v5 app to v6 and can't get it working just by setting isDrawingMode on the canvas to true. (It worked in my v5 app.)

ShaMan123 commented 1 year ago

Yes, thanks! Canvas#freeDrawingBrush is not set by default. so just canvas.freeDrawingBrush = new PencilBrush()

hanna-becker commented 1 year ago

Yes, thanks! Canvas#freeDrawingBrush is not set by default. so just canvas.freeDrawingBrush = new PencilBrush()

This worked. Thank you!

abdussami-tayyab commented 1 year ago

@asturur and @ShaMan123 I will start off by saying that first of all thank you for this version, it automatically helps resolve a lot of issues for me at work (most importantly object manipulation in groups (although it breaks for nested groups but that's not the purpose of this comment))

The issue is documented in this CodeSandbox (my original version is beta7 but this sandbox only had beta1), but it's also appearing here. The issue is that when I save JSON in my Firestore database (via canvas.toJSON) and try to load it via loadFromJSON, it just... throws many strange errors. Sometimes it would say No class registered for Group and sometimes it would say can't set _set on null e.

What is weird that I did not face any issue of this sort on v5 but it's breaking for v6. @ShaMan123 is it also the right way I have setup code in React in your opinion?

Happy to provide more info if needed!

edit: there's also the issue that it sometimes works fine locally and also loads the objects on canvas, but they're invisible, only when I click them do they become visible.

ShaMan123 commented 1 year ago

I didn't look into your sandbox but it is probably #9009 Open a dedicated issue next time

asturur commented 1 year ago

Added: https://github.com/fabricjs/fabric.js/pull/9018/

duydodevgithub commented 1 year ago

Hi @ShaMan123 @asturur , do you have ETA for the v6 release and not sure if we have a documentation for it yet? I am working on upgrading from v2x to v5, maybe I will wait for v6 since it has Promise support. Thank you so much for this version !

hanna-becker commented 1 year ago

I noticed that the type support for canvas.getActiveObject() is off. I was chasing down a bug because I was unaware it returned a Promise. Usually my IDE warns me about unhandled promises, but it didn't for this one, and jumping into the definition shows me this, which can't be right:

  getActiveObject(): FabricObject | undefined {
    return this._activeObject;
  }

ShaMan123 commented 1 year ago

I noticed that the type support for canvas.getActiveObject() is off. I was chasing down a bug because I was unaware it returned a Promise. Usually my IDE warns me about unhandled promises, but it didn't for this one, and jumping into the definition shows me this, which can't be right:
  getActiveObject(): FabricObject | undefined {
    return this._activeObject;
  }

It is correct, no promise

kyun commented 1 year ago

Hi, I am going to start new project with fabric.js and typescript. My question is which version should I use in production? v6 beta or v5 ? I am afraid to migrate v5 to v6. At the same time, I am not sure it is right to use beta version in production. Please give me advice.

ShaMan123 commented 1 year ago

We are working on v6 for our projects. Typescript in v6 only. The amount of fixes in v6 is overwhelming. Since you are starting, v6 is the right choice IMO - you decide

bladerunner2020 commented 1 year ago

We use 6 beta in prod. So far so good)

hanna-becker commented 1 year ago

Same here. We started a new project with v6 a month ago and it's running in production now. No regrets so far.

thisisdice commented 1 year ago

How can we use fabric.util.addClass?

Tried converting some class based examples from the fabric js website but Im running into issues.

import React, { useEffect, useRef } from 'react';
import * as fabric from 'fabric';

const AnimatedCross = ({ canvas }) => {
  const crossRef = useRef(null);

  useEffect(() => {
    const Cross = fabric.util.createClass(fabric.Object, {
      objectCaching: false,
      initialize: function (options) {
        this.callSuper('initialize', options);
        this.animDirection = 'up';

        this.width = 100;
        this.height = 100;

        this.w1 = this.h2 = 100;
        this.h1 = this.w2 = 30;
      },

      animateWidthHeight: function () {
        const interval = 2;

        if (this.h2 >= 30 && this.h2 <= 100) {
          const actualInterval = this.animDirection === 'up' ? interval : -interval;
          this.h2 += actualInterval;
          this.w1 += actualInterval;
        }

        if (this.h2 >= 100) {
          this.animDirection = 'down';
          this.h2 -= interval;
          this.w1 -= interval;
        }
        if (this.h2 <= 30) {
          this.animDirection = 'up';
          this.h2 += interval;
          this.w1 += interval;
        }
      },

      _render: function (ctx) {
        ctx.fillRect(-this.w1 / 2, -this.h1 / 2, this.w1, this.h1);
        ctx.fillRect(-this.w2 / 2, -this.h2 / 2, this.w2, this.h2);
      },
    });

    const cross = new Cross({ top: 100, left: 100 });
    crossRef.current = cross;
    canvas.add(cross);

    const animate = () => {
      cross.animateWidthHeight();
      cross.dirty = true;
      canvas.renderAll();
      requestAnimationFrame(animate);
    };

    animate();
  }, [canvas]);

  return null;
};

export default AnimatedCross;

ShaMan123 commented 1 year ago

@thisisdice I have removed your comment since it is spamming, proof is you couldn't see my previous comment

moved to native classes => no more createClass

Originally posted by @ShaMan123 in https://github.com/fabricjs/fabric.js/issues/8299#issuecomment-1427028792

@asturur please update the desc to include classes and prototype changes (props, ownDefaults, etc.)

ShaMan123 commented 1 year ago

@abdussami-tayyab open an issue, reproduce it properly. Bugs are to be fixed, not worked around.

ShaMan123 commented 1 year ago

ActiveSelection is a constant ref on canvas canvas.setActiveObject(new ActiveSelection()) will break selection #9066

enriqueerrando commented 1 year ago

Hi @ShaMan123 !!

How is the beta going? Is it close to the v6 release?

Thanks in advance!

ShaMan123 commented 1 year ago

V6 is doing good Unfortunately timelines are not available. Everyone, including the team, wants it out already. I encourage everyone to move to beta now as it requires work and a change of some points in mindset. Contributions are welcome always. Testing is becoming easier thanks to playwright so contributing might become easier as well hopefully.

chau-a-nguyen commented 1 year ago

Is playwright used for e2e testing and/or more? Is there a main page for V6 for status, getting started, API, installing, running locally for contributing, examples, best implemented editors, etc.?

ShaMan123 commented 1 year ago

Is playwright used for e2e testing and/or more?

hmmm. I don't know. We just introduced it. I have been experimenting the past few days. Have any suggestions?

Is there a main page for V6 for status, getting started, API, installing, running locally for contributing, examples, best implemented editors, etc.?

There is this ticket. The README.md and CONTRIBUTING.md are pretty much up to date, if not or if irrelevant please say so/PR.

Ping me if that is not enough, I'd be happy to lend a hand.

ShaMan123 commented 1 year ago

For the greater community:

We want to wrap up the TS migration and we need help.

Contributions are needed!

Current task is to type the remaining files and address TS errors. Contributors can search for files with @ts-nocheck and get to work. Open a draft PR with the title chore(TS): [SCOPE] once you get started stating which files you wish to address so people don't work on the same thing. Then when you are done, move it out of the draft state and review it and then one of us will review as well. Be sure to check for open PRs before you start working. If someone wishes to do it all go ahead.

Thanks!

chau-a-nguyen commented 1 year ago

Is playwright used for e2e testing and/or more?

hmmm. I don't know. We just introduced it. I have been experimenting the past few days. Have any suggestions?

Typically used for e2e testing, could be used to automate other things in the browser. Would suggest to use shared/reusable page objects. https://playwright.dev/docs/pom

hsbtr commented 1 year ago

Initialization threw an error

trying to initialize a canvas that has already been initialized at CanvasDOMManager.createLowerCanvas

hsbtr commented 1 year ago

Initialization threw an error

trying to initialize a canvas that has already been initialized at CanvasDOMManager.createLowerCanvas

The problem was finally found to be caused by executing react useEffect twice

hsbtr commented 1 year ago

It is recommended to export the options types of Rect Circle Line and other classes in fabric.ts, because importing the declaration files of these classes alone will trigger eslinet prettier warnings

At the same time, the options of canvas lack the type declaration

ShaMan123 commented 1 year ago

@hsbtr You should open an issue for this. Object options are now exported Exporting canvas options is a todo

hanna-becker commented 1 year ago

When using canvas.loadFromJSON how can we handle images with outdated src properties returning 404s? I tried using the method's reviver arguments to handle this gracefully, but it looks like the callback is running when it's already too late.

ShaMan123 commented 1 year ago

Please do not abuse this ticket, we do not want to lock it. Use the appropriate channels (issues, discussions etc.)

jiayihu commented 1 year ago

centerPoint doesn't exist anymore as initialization option to fabric.Group
groupSVGElements doesn't accept the initial Group options anymore <= as it is now, it's not useful at all. Could be just removed
loadSVGFromURL signature changed, it's returning a Promise now

sukbearai commented 1 year ago

什么时候能实现？

jamesshaw1987 commented 1 year ago

A few notes from my migration from v5 to v6:

Setting background image based on a data URL

canvas.setBackgroundImage(source.toDataURL(), renderCallback, options)

can become

canvas.backgroundImage = new fabric.Image(source, options)

PencilBrush._drawSegment is now PencilBrush.drawSegment
Accessing fabric.document and fabric.window directly has been replaced by fabric.getFabricDocument()/fabric.getFabricWindow()
PencilBrush._captureDrawingPath(pointer) can be replaced with PencilBrush._addPoint(new fabric.Point(pointer.x, pointer.y))

jiayihu commented 1 year ago

什么时候能实现？

他们正在修复最后的错误，几周后应该就可以了

zhengguorong commented 1 year ago

I use 6.x in my project and everything looks good, but EraserBrush can not be use. finially, I rollback to 5.x version 😭

ShaMan123 commented 1 year ago

@zhengguorong subscribe to #8499

mindmind commented 1 year ago

Hey, do you have plans to implement kinda cornerBorderScaleFactor for changing the width of control borders? If yes, then I can try to contribute. My team really need it.

tasnim-reza commented 1 year ago

Trying to use "fabric": "v6.0.0-beta13" with Angular 15, getting the following error, do you know what is wrong?

jiayihu commented 1 year ago

Trying to use "fabric": "v6.0.0-beta13" with Angular 15, getting the following error, do you know what is wrong?

I'd recommend using skipLibCheck in the tsconfig.json to avoid TS type checking the libs, including fabric. For the toObject issue you can see https://github.com/fabricjs/fabric.js/pull/9014

asturur commented 1 year ago

Hey, do you have plans to implement kinda cornerBorderScaleFactor for changing the width of control borders? If yes, then I can try to contribute. My team really need it.

Open a discussion or a feature request with a screenshot of what you would like to get. Some of the answers could include that you can simply make your control render function with zero issues.

chrisp018 commented 1 year ago

FYI. There is a break when upgrade the nextjs version from 13.4.19 to 13.5.1 for case using useEffect. My solution for now is revert next to previous version. Please refer to the screenshot for error message:

export default function Studio() {
  useEffect(() => {
    const canvas = new fabric.Canvas("canvas", {
      height: 500,
      width: 800,
      backgroundColor: "#ededed",
    })
  }, [])

  return (
    <div>
      <canvas id="canvas" className="h-[500px] w-[800px]" />
    </div>
  )
}

package.json

{
  ...
  "dependencies": {
    ...
    "fabric": "^6.0.0-beta13",
    "next": "13.5.1",
    ...
  },
}

fabricjs / fabric.js