Migrating from v2 to v3

Make sure to read through the following steps to ensure a smooth upgrade from v2 to v3 of this package.

• The package is ESM only
• The withVue2 decorator is removed
• Breakpoints are no longer read from the DOM
• The focusTrap export has been refactored
• The loaded hook has been removed
• The return value of the scrollTo function has changed
• The on... method arguments have been refactored
• Lifecycle methods are now async
• Unconfigured events are not listenable anymore
• Custom events are now emitted on the root element

The package is ESM only

Introduced in #394, the package is now ESM only and does not include CJS files anymore.

This should have no impact on most projects as files are handled by bundlers most of the time.

The withVue2 decorator is removed

The withVue2 decorator is removed, along with the package's dependency to the vue@2 package.

If your project is using this decorator, you can copy the latest version from the package in your project and keep using it.

See pull-request #395 for more details.

Breakpoints are no longer read from the DOM

In the previous versions, breakpoints values for the resize service were read from the DOM by looking for a [data-breakpoint] element. In v3, this is no longer supported, breakpoints should be defined when creating your app with the createApp() function.

- <div data-breakpoint>…</div>

export default createApp(App, document.body); 
export default createApp(App, { 
  root: document.body, 
  screens: { 
    s: '30rem', 
    m: '60rem', 
    l: '90rem', 
  }, 
}); 

The focusTrap export has been refactored

In v2 you had to import the focusTrap function and then execute it to get the trap and untrap functions.

The trap and untrap functions are now exported directly as trapFocus and untrapFocus.

import { trapFocus } from '@studiometa/js-toolkit/utils'; 
import { trapFocus, untrapFocus } from '@studiometa/js-toolkit/utils'; 

const { trap, untrap } = trapFocus(); 
trap(element, event); 
untrap(); 
trapFocus(element, event); 
untrapFocus(); 

The loaded hook has been removed

In the previous versions, a loaded hook was present on any component extending the Base class. It was triggered by the load event on the window. Due to its ease of implementation and its low usage, it has been removed.

import { Base } from '@studiometa/js-toolkit';}

class Component extends Base {
  static config = {
    name: 'Component',
  };

  loaded() { 
    console.log('page is loaded') 
  mounted() { 
    window.addEventListener('load', () => { 
      console.log('page is loaded'); 
    }); 
  }
}

You can still use the useLoad service as a replacement if needed, as it handles the possibility of the load event having been fired already.

The return value of the scrollTo function has changed

Previously, the scrollTo function could only be used to scroll vertically. It can now scroll horizontally as well. With this new feature, we had to change the return type of the function from Promise<number> to Promise<{ top: number, left: number }>.

import { scrollTo } from '@studiometa/js-toolkit/utils';

const scrollY = await scrollTo('#target'); 
const { left: scrollY } = await scrollTo('#target'); 

The on... method arguments have been refactored

The number of arguments passed to the on... methods and their order were different for each type of target: a child component, a ref, the current instance, etc. In v3, all on... methods receive a single context argument of the following type:

type EventHooksCallbackParams = {
  event: Event;
  args: Array<any>;
  index: number;
  target: Element | Base | Promise<Base> | typeof window | typeof document;
};

To migrate from v2 to v3, update the arguments of all your on... methods:

class Component extends Base {
  onClick(event) { 
  onClick({ event }) { 
    event.preventDefault();
  }

  onCustomEvent(event, arg1, arg2) { 
  onCustomEvent({ args: [arg1, arg2] }) { 
    console.log(arg1, arg2);
  }

  onRefClick(event, index) { 
  onRefClick({ target }) { 
    const target = this.$refs.Ref[index]; 
    target.classList.toggle('is-active');
  }

  onChildCustomEvent(event, arg1, index) { 
  onChildCustomEvent({ target }) { 
    const target = this.$children.Child[index]; 
    target.doSomething()
  }
}

Lifecycle methods are now async

The $mount, $update, $destroy and $terminate methods are now async and can be awaited. This should not have a big impact on existing projects, but in case you are trying to access a newly mounted child component after calling the $update() method, you should await its result to be sure the component is mounted.

this.$update(); 
await this.$update(); 
this.$children.Component[0].toggle();

Unconfigured events are not listenable anymore

In v2, custom events that were not configured via the static config property were still taken in consideration when adding event listeners with the $on method or the on... event hooks. This behavior is removed in v3, meaning that each component must define the events it will emit.

To migrate, make sure to add the events that will be emitted to the static config object with the emits property.

class MyComponent extends Base {
  static config = {
    name: 'MyComponent',
    emits: ['custom-event'], 
  };

  mounted() {
    this.$emit('custom-event');
  }

  onCustomEvent() {
    // ...
  }
}

Custom events are now emitted on the root element

In v2, events defined on an instance were dispatched on the instance itself. With v3, the custom events defined in the config.emits configuration are now dispatched on the instance root element.

This is considered a breaking change for the following reason:

• The Base class no longer extends the EventTarget class
• Custom event emitted might conflict with native events