Migration guides for Maker major releases

17.x -> 18.x (PR)

Standardizes size values for MIcon & MLoading

The size prop values for MLoading did not match those of MIcon, which is a problem because MLoading was recently refactored to use MIcon internally. They now match. Also the size prop for either MLoading or MIcon can now also take any arbitrary valid CSS value for width or height. The default sizes for both components remains unchanged.

size	MIcon 17.x	MLoading 17.x	MIcon 18.x	MLoading 18.x
16px	`medium`	`medium`	`small`	`small`
24px	`large`	-	`medium`	`medium`
32px	-	-	`large`	`large`
40px	-	-	`xlarge`	`xlarge`
48px	`xlarge`	-	`xxlarge`	`xxlarge`
56px	-	-	`56px`	`56px`
64px	`xxlarge`	`large`	`64px`	`64px`

17.x (before)	18.x (after)
`<m-icon />`	`<m-icon />` (no changes)
`<m-icon size="medium" />`	`<m-icon size="small" />`
`<m-icon size="large" />`	`<m-icon size="medium" />`
`<m-icon size="xlarge" />`	`<m-icon size="xxlarge" />`
`<m-icon size="xxlarge" />`	`<m-icon size="64px" />`
`<m-loading />`	`<m-loading />` (no changes)
`<m-loading size="medium" />`	`<m-loading size="small" />`
`<m-loading size="large" />`	`<m-loading size="64px" />`

16.x -> 17.x (PR)

Theme icons now using render functions

Before to theme icons you'd have to pass Vue components to the MTheme config object. This had two big limitations: icon components must be compiled either ahead of time or on the fly, and it wasn't possible to customize the prop values on the icon component, it would always be rendered with the defaults. Furthermore, doing this just for icon components was a little odd since we already established the pattern of using render functions for all other components which conditionally render nested content, e.g. MModals, MDialogs, MBlades, MToasts. Now to theme icons you use render functions, which solves all of the problems noted above.

16.x (before)	17.x (after)
`const theme = { icons: { error: AlertTriangle } };`	`const theme = { icons: { error: (h) => h(AlertTriangle) } };`
`<m-icon name="error" />`	`<m-icon name="error" />` (no changes)

15.x -> 16.x (PR)

`parentModal` removed from `modalApi`, use `closeAll` instead

Before, if a user wanted to close a stack of modals simultaneously, they would write this.modalApi.parentModal.close(), which worked at some point in time, but has been broken for a while, and even while it "worked" it would force close both modals without running their beforeClose hooks. For these reasons parentModal has been removed and replaced with a closeAll method which solves all of these problems.

15.x (before)	16.x (after)
`this.modalApi.parentModal.close()`	`this.modalApi.closeAll()`

MLoading `normal` size renamed to `medium`

The naming scheme for Maker component semantic sizes is: xsmall, small, medium, large, xlarge but MLoading was implemented forever ago and its size values were normal and large which is weird so we're renaming normal to medium so it's more consistent with the rest of the library.

15.x (before)	16.x (after)
`<m-loading size="normal" />`	`<m-loading size="medium" />`

MMenuOption `click-handler` prop removed, use `@click` instead

Should've been @click from the beginning, but was overlooked during code review.

15.x (before)	16.x (after)
`<m-menu-option :click-handler="someMethod">`	`<m-menu-option @click="someMethod">`

`critical` theme value renamed to `error`

We've been using critical and error interchangeably internally within the library but also in the public API, so it sometimes got confusing when to use one or the other, so we're simplifying the situation by standardizing on error in all use-cases.

15.x (before)	16.x (after)
`{ colors: { critical: { /* colors here */ }}}`	`{ colors: { error: { /* colors here */ }}}`
`@colors.critical.onFill`	`@colors.error.onFill`
`@colors.critical.fill`	`@colors.error.fill`
`@colors.critical.text`	`@colors.error.text`
`@colors.critical.subtle`	`@colors.error.subtle`
`var(--maker-color-critical-fill)`	`var(--maker-color-error-fill)`
`{ icons: { critical: AlertTriangle }}`	`{ icons: { error: AlertTriangle }}`
`@icons.critical`	`@icons.error`
`<m-icon name="critical" />`	`<m-icon name="error" />`
`<m-notice icon-name="critical">`	`<m-notice icon-name="error">`
`<m-progress-circle icon-name="critical">`	`<m-progress-circle icon-name="error">`
`<m-toast icon-name="critical">`	`<m-toast icon-name="error">`

MThumbnails `size` prop now takes strings instead of numbers

Before the MThumbnails size prop only took a number, and converted it to pixels, to set the thumbnail size. Now it takes a string, which can be any valid CSS width or height value. This is now more similar to how most props on most components work.

15.x (before)	16.x (after)
`<m-thumbnails :size="100">`	`<m-thumbnails size="100px">`

Added `show-icon` prop to MProgressCircle

MProgressCircle's icon props were not pattern-friendly. We had the same problem during the development of MToast and we solved it by adding a show-icon prop which we've now also added to MProgressCircle. You know have to set this prop to true along with passing an icon name to display an icon.

15.x (before)	16.x (after)
`<m-progress-circle icon-name="info">`	`<m-progress-circle icon-name="info" show-icon>`

All components moved from `/utils` to `/components`

Before we put visual components into /components and functional components into /utils. This seemed like a meaningful distinction at the time but we no longer feel it warrants separating the components into these arbitrary categories, especially considering that we currently have several components like MRow, MBlockFormControlLayout, MInlineFormControlLayout, MDialogLayer, MToastLayer, and MBladeLayer that blur this boundary, and we have several potential components coming down the pipeline like MLayout, MGrid, MCarousel, and MSlideshow that further blur the boundary. Keeping track of this arbitrary categorization is also a burden we passed on to our users who had to remember whether a component is a "regular" component or a "utility" component in order to import it correctly. We decided to get rid of the arbitrary categorization and now all components are in the /components directory.

15.x (before)	16.x (after)
`import { MBlockFormControlLayout } from '@square/maker/utils/BlockFormControlLayout'`	`import { MBlockFormControlLayout } from '@square/maker/components/BlockFormControlLayout'`
`import { MInlineFormControlLayout } from '@square/maker/utils/InlineFormControlLayout'`	`import { MInlineFormControlLayout } from '@square/maker/components/InlineFormControlLayout'`
`import { MRow } from '@square/maker/utils/Row'`	`import { MRow } from '@square/maker/components/Row'`
`import { MTouchCapture } from '@square/maker/utils/TouchCapture'`	`import { MTouchCapture } from '@square/maker/components/TouchCapture'`
`import { MTransition } from '@square/maker/utils/Transition'`	`import { MTransition } from '@square/maker/components/Transition'`
`import { MTransitionCollapse } from '@square/maker/utils/TransitionCollapse'`	`import { MTransitionCollapse } from '@square/maker/components/TransitionCollapse'`
`import { MTransitionFadeIn } from '@square/maker/utils/TransitionFadeIn'`	`import { MTransitionFadeIn } from '@square/maker/components/TransitionFadeIn'`
`import { MTransitionResize } from '@square/maker/utils/TransitionResize'`	`import { MTransitionResize } from '@square/maker/components/TransitionResize'`
`import { MTransitionResponsive } from '@square/maker/utils/TransitionResponsive'`	`import { MTransitionResponsive } from '@square/maker/components/TransitionResponsive'`
`import { MTransitionSpringLeft } from '@square/maker/utils/TransitionSpringLeft'`	`import { MTransitionSpringLeft } from '@square/maker/components/TransitionSpringLeft'`
`import { MTransitionSpringUp } from '@square/maker/utils/TransitionSpringUp'`	`import { MTransitionSpringUp } from '@square/maker/components/TransitionSpringUp'`
`import { MTransitionStack } from '@square/maker/utils/TransitionStack'`	`import { MTransitionStack } from '@square/maker/components/TransitionStack'`
`import { MTransitionStaggered } from '@square/maker/utils/TransitionStaggered'`	`import { MTransitionStaggered } from '@square/maker/components/TransitionStaggered'`

14.x -> 15.x (PR)

MButton pattern & variant renames

MButton patterns primary, secondary, and tertiary have been removed since they're identical to variants fill, outline, and ghost respectively. MButton variants primary, secondary, and tertiary have also been renamed to fill, outline, and ghost respectively. Filled button patterns primaryFilled, errorFilled , successFilled , warningFilled, infoFilled have been renamed to primaryFill, errorFill , successFill, warningFill, infoFill.

before (14.x)	after (15.x)
`<m-button>`	`<m-button>` (no changes)
`<m-button variant="primary">`	`<m-button variant="fill">`
`<m-button variant="secondary">`	`<m-button variant="outline">`
`<m-button variant="tertiary">`	`<m-button variant="ghost">`
`<m-button pattern="primary">` **	`<m-button variant="fill">`
`<m-button pattern="secondary">` **	`<m-button variant="outline">`
`<m-button pattern="tertiary">` **	`<m-button variant="ghost">`
`<m-button pattern="primaryFilled">`	`<m-button pattern="primaryFill">`
`<m-button pattern="errorFilled">`	`<m-button pattern="errorFill">`
`<m-button pattern="successFilled">`	`<m-button pattern="successFill">`
`<m-button pattern="warningFilled">`	`<m-button pattern="warningFill">`
`<m-button pattern="infoFilled">`	`<m-button pattern="infoFill">`

Note: If you were using these deprecated patterns in a custom theme and wish to continue using them, you can update them from this:

button: {
  patterns: {
    primary: {
      /* customizations */
    },
    secondary: {
      /* customizations */
    },
    tertiary: {
      /* customizations */
    },
  },
},

To this:

button: {
  patterns: {
    primary: {
      variant: 'fill',
      /* customizations */
    },
    secondary: {
      variant: 'outline',
      /* customizations */
    },
    tertiary: {
      variant: 'ghost',
      /* customizations */
    },
  },
},

MNotice prop `variant` renamed to `display`

MNotice's variant prop has been renamed to display.

before (14.x)	after (15.x)
`<m-notice>`	`<m-notice>` (no changes)
`<m-notice variant="inline">`	`<m-notice display="inline">`
`<m-notice variant="block">`	`<m-notice display="block">`

Default theme changes

NOTE: If you're using MTheme at the root of your app and setting an explicit primary color then these changes won't affect your app. These changes only affect people who are using Maker without MTheme or with MTheme but aren't setting an explicit primary color and have been relying on the implicit primary color being #000000.

Within the default theme the primary color has changed from #000000 to #006aff, the derived contextual primary colors have been updated, the overlay color has changed from rgba(0, 0, 0, 0.3) to rgba(0, 0, 0, 0.32). The default parameters within the maker-colors utility function have also been updated accordingly.

If you weren't using MTheme before and relying on the implicit primary color being #000000, e.g.

<template>
  <div id="app">
    <m-button>
      i expect this button to be #000000
      but if i migrate to 15.x it will be #006aff
    </m-button>
  </div>
</template>

You will now have to import MTheme and explicitly set the primary color to #000000, e.g.

<template>
  <div id="app">
    <m-theme :theme="{ colors: { primary: '#000000' }, }">
      <m-button>
        now this button is guaranteed to be
        #000000 in both 14.x and 15.x
      </m-button>
    </m-theme>
  </div>
</template>

Also, if you were previously using the maker-colors utility function and relying on the implicit primary color being #000000 by calling the function with only the first parameter, e.g. makerColors(bgColor), then you now also have to pass #000000 as an explicit 2nd argument to maintain the same appearance in your app migrating to 15.x from 14.x, e.g. makerColors(bgColor, '#000000'). Again, if you were already using the utility function with an explicit 2nd parameter in 14.x, makerColors(bgColor, primaryColor), then you do not have to make any changes when migrating to 15.x.

13.x -> 14.x (PR)

Transition components moved from `/components` to `/utils`

before (13.x)	after (14.x)
`import { MTouchCapture } from '@square/maker/components/TouchCapture';`	`import { MTouchCapture } from '@square/maker/utils/TouchCapture';`
`import { MTransitionFadeIn } from '@square/maker/components/TransitionFadeIn';`	`import { MTransitionFadeIn } from '@square/maker/utils/TransitionFadeIn';`
`import { MTransitionResize } from '@square/maker/components/TransitionResize';`	`import { MTransitionResize } from '@square/maker/utils/TransitionResize';`
`import { MTransitionSpringLeft } from '@square/maker/components/TransitionSpringLeft';`	`import { MTransitionSpringLeft } from '@square/maker/utils/TransitionSpringLeft';`
`import { MTransitionSpringUp } from '@square/maker/components/TransitionSpringUp';`	`import { MTransitionSpringUp } from '@square/maker/utils/TransitionSpringUp';`
`import { MTransitionStaggered } from '@square/maker/components/TransitionStaggered';`	`import { MTransitionStaggered } from '@square/maker/utils/TransitionStaggered';`

Other transition components like MTransition and MTransitionResponsive were already in the /utils directory so if you were using those then those imports don't require any updates.

12.x -> 13.x (PR)

`profiles` refactored from keyed array into object

The profiles field within theme config objects has been changed from a keyed array to an object. You should refactor your code to change profiles from a keyed array to an object. Example of what profiles looked like before:

// 12.x (before)
// keyed array
[
  {
    id: 'light-profile',
    colors: { /* whatever */ },
  },
  {
    id: 'dark-profile',
    colors: { /* whatever */ },
  },
]

Example of what profiles should look like now:

// 13.x (after)
// object
{
  'light-profile': {
    colors: { /* whatever */ },
  },
  'dark-profile': {
    colors: { /* whatever */ },
  },
}

11.x -> 12.x (PR)

`chroma-js` removed, replaced by `colord`

Maker peer dependencies have changed. chroma-js has been replaced by colord. In your package.json:

11.x (before)	12.x (after)
`"chroma-js": "^2.1.0"`	`"colord": "^2.9.2"`

9.x -> 11.x (PR)

10.x was skipped.

MHeading was removed, replaced with MText

9.x (before)	11.x (after)
`import { MHeading } from '@square/maker/components/Heading'`	`import { MText } from '@square/maker/components/Text'`
`<m-heading>`	`<m-text pattern="title">`

Typography now globally themeable

Any theming configs you had for heading and text should be moved into the new fonts config of the theme object. Take these:

// in theme object
heading: {
  fontFamily: 'headingFontFamily',
  fontWeight: 'headingFontWeight',
},
text: {
  fontFamily: 'textFontFamily',
  fontWeight: 'textFontWeight',
},

And move them here:

// in theme object
fonts: {
  heading: {
    fontFamily: 'headingFontFamily',
    fontWeight: 'headingFontWeight',
  },
  body: {
    fontFamily: 'textFontFamily',
    fontWeight: 'textFontWeight',
  },
},

Public CSS variables renamed

9.x (before)	11.x (after)
`--neutral-0`	`--maker-color-neutral-0`
`--neutral-10`	`--maker-color-neutral-10`
`--neutral-20`	`--maker-color-neutral-20`
`--neutral-80`	`--maker-color-neutral-80`
`--neutral-90`	`--maker-color-neutral-90`
`--neutral-100`	`--maker-color-neutral-100`
`--color-primary`	`--maker-color-primary`
`--color-background`	`--maker-color-background`
`--color-heading`	`--maker-color-heading`
`--maker-color-title`	`--maker-color-heading`
`--color-text`	`--maker-color-body`
`--maker-color-paragraph`	`--maker-color-body`
`--color-elevation`	`--maker-color-elevation`
`--color-overlay`	`--maker-color-overlay`
`--font-family-title`	`--maker-font-heading-font-family`
`--maker-font-family-title`	`--maker-font-heading-font-family`
`--font-weight-title`	`--maker-font-heading-font-weight`
`--maker-font-weight-title`	`--maker-font-heading-font-weight`
`--font-family-paragraph`	`--maker-font-body-font-family`
`--maker-font-family-paragraph`	`--maker-font-body-font-family`
`--font-weight-paragraph`	`--maker-font-body-font-weight`
`--maker-font-weight-paragraph`	`--maker-font-body-font-weight`
`--font-family-label`	`--maker-font-label-font-family`
`--maker-font-family-label`	`--maker-font-label-font-family`
`--font-weight-label`	`--maker-font-label-font-weight`
`--maker-font-weight-label`	`--maker-font-label-font-weight`

Prefer patterns over variants for MButtons

Although the variant prop has not been deprecated, it's almost always more correct to use pattern for MButtons now.

9.x (before)	11.x (after)
`<m-button variant="primary">`	`<m-button pattern="primary">`
`<m-button variant="secondary">`	`<m-button pattern="secondary">`
`<m-button variant="tertiary">`	`<m-button pattern="tertiary">`

Miscellaneous

If you don't want to set a themeable prop but must pass some null-ish value then '' (empty string) no longer works for that use-case, you must now explicitly pass undefined.
Margin was removed from <m-text element="p"> (p is the default), and if you want to maintain margin on these elements you now need to add it with your own CSS

8.x -> 9.x (PR)

Theme component majorly refactored

Prior to this release MTheme was nonfunctional so nobody should have been using it so although it received major refactors it should not require any code refactors in user code.

Text component props were renamed

8.x (before)	9.x (after)
`<m-text text-color="#000">`	`<m-text color="#000">`
`<m-heading text-color="#000">`	`<m-heading color="#000">`

7.x -> 8.x (PR)

Dropped support for UC Android & Opera Mini browsers

No code refactors necessary.

6.x -> 7.x (PR)

MTextButton moved from `/Button` to `/TextButton`

6.x (before)	7.x (after)
`import { MTextButton } from '@square/maker/components/Button'`	`import { MTextButton } from '@square/maker/components/TextButton'`

5.x -> 6.x (PR)

MSection removed, replaced with MContainer

5.x (before)	6.x (after)
`import { MSection } from '@square/maker/components/Section'`	`import { MContainer } from '@square/maker/components/Container'`
`<m-section>`	`<m-container bg-color="#fff">`

4.x -> 5.x (PR)

MNoticeButton removed, replaced with MTextButton

4.x (before)	5.x (after)
`import { MNoticeButton } from '@square/maker/components/Notice'`	`import { MTextButton } from '@square/maker/components/Button'`
`<m-notice-button>`	`<m-text-button>`

3.x -> 4.x (PR)

`lodash` dependency was externalized

No code refactors necessary.

2.x -> 3.x (PR)

`date-fns` dependency was externalized

No code refactors necessary.

1.x -> 2.x (PR)

Peer dependencies changed

Update peer dep popmotion from 8.x to ^9.3.1
Add new peer dep stylefire to ^7.0.3

Transition components renamed

1.x (before)	2.x (after)
`import { MTransitionFade } from '@square/maker/components/TransitionFade'`	`import { MTransitionFadeIn } from '@square/maker/components/TransitionFadeIn'`
`import { MTransitionSpring } from '@square/maker/utils/TransitionSpring'`	`import { MTransition } from '@square/maker/utils/Transition'`
`import { MTransitionSpringResponsive } from '@square/maker/utils/TransitionSpringResponsive'`	`import { MTransitionResponsive } from '@square/maker/utils/TransitionResponsive'`
`<m-transition-fade>`	`<m-transition-fade-in>`
`<m-transition-spring>`	`<m-transition>`
`<m-transition-spring-responsive>`	`<m-transition-responsive>`

Transition props changed

MTransition and MTransitionResponsive now take transition functions instead of popmotion config objects.

Files

MIGRATION.md

Latest commit

History

MIGRATION.md

File metadata and controls

Migration guides for Maker major releases

17.x -> 18.x (PR)

Standardizes size values for MIcon & MLoading

16.x -> 17.x (PR)

Theme icons now using render functions

15.x -> 16.x (PR)

parentModal removed from modalApi, use closeAll instead

MLoading normal size renamed to medium

MMenuOption click-handler prop removed, use @click instead

critical theme value renamed to error

MThumbnails size prop now takes strings instead of numbers

Added show-icon prop to MProgressCircle

All components moved from /utils to /components

14.x -> 15.x (PR)

MButton pattern & variant renames

MNotice prop variant renamed to display

Default theme changes

13.x -> 14.x (PR)

Transition components moved from /components to /utils

12.x -> 13.x (PR)

profiles refactored from keyed array into object

11.x -> 12.x (PR)

chroma-js removed, replaced by colord

9.x -> 11.x (PR)

MHeading was removed, replaced with MText

Typography now globally themeable

Public CSS variables renamed

Prefer patterns over variants for MButtons

Miscellaneous

8.x -> 9.x (PR)

Theme component majorly refactored

Text component props were renamed

7.x -> 8.x (PR)

Dropped support for UC Android & Opera Mini browsers

6.x -> 7.x (PR)

MTextButton moved from /Button to /TextButton

5.x -> 6.x (PR)

MSection removed, replaced with MContainer

4.x -> 5.x (PR)

MNoticeButton removed, replaced with MTextButton

3.x -> 4.x (PR)

lodash dependency was externalized

2.x -> 3.x (PR)

date-fns dependency was externalized

1.x -> 2.x (PR)

Peer dependencies changed

Transition components renamed

Transition props changed

`parentModal` removed from `modalApi`, use `closeAll` instead

MLoading `normal` size renamed to `medium`

MMenuOption `click-handler` prop removed, use `@click` instead

`critical` theme value renamed to `error`

MThumbnails `size` prop now takes strings instead of numbers

Added `show-icon` prop to MProgressCircle

All components moved from `/utils` to `/components`

MNotice prop `variant` renamed to `display`

Transition components moved from `/components` to `/utils`

`profiles` refactored from keyed array into object

`chroma-js` removed, replaced by `colord`

MTextButton moved from `/Button` to `/TextButton`

`lodash` dependency was externalized

`date-fns` dependency was externalized