Improve upgrade guide documentation (#651)

CHANGELOG.md

@@ -2,6 +2,8 @@
 
 ## Not released
 
+- Improve upgrade guide documentation [#651](https://github.com/CartoDB/carto-react/pull/651)
+
 ## 2.0
 
 ### 2.0.1 (2023-04-14)

UPGRADE.md

@@ -2,12 +2,12 @@
 
 # Breaking changes in Mui v5
 
-Please, follow the Mui guides related to breaking changes in components and styles:
+Please, follow the `Mui official guides` related to breaking changes in components and styles:
 
 - [Styles](https://mui.com/material-ui/migration/v5-style-changes/)
 - [Components](https://mui.com/material-ui/migration/v5-component-changes/)
 
-# MUI theme
+# CARTO MUI theme
 
 [carto-theme.js](https://github.com/CartoDB/carto-react/blob/master/packages/react-ui/src/theme/carto-theme.js) file splitted in sections:
 
@@ -41,6 +41,8 @@ Tip: An easy search to catch up this, would be `-theme.spacing(`
 
 ## Icons
 
+### Colors
+
 We have this kind of rules in buttons to cover the common use cases:
 
 `svg path { fill: currentColor }`
@@ -49,36 +51,48 @@ In case you don't need the icon to be filled, you can apply this class to the sv
 
 `<CloseIcon className="doNotFillIcon" />`
 
-## Typography
+### Sizes
+
+We have 3 defined sizes that can be added with the `fontSize` prop of `SvgIcon` component.
+
+- small
+- medium (default)
+- large
+
+Note: the most common use case is to have the icons at medium size (`18px`), there is only a few exceptions where they use other sizes.
+
+## Typography styles
 
 `responsiveFontSizes` simplified due we want to resize only a few variants through the theme.
 
-Added a few custom variants to the typography set:
+### New variants
 
 - overlineDelicate
 - code1
 - code2
 - code3
 
-Some variants have been replaced because they were so specific to some components, these are:
+### Replaced variants
 
-- charts (replaced by `theme.palette.overline + weight='strong'`)
+Replaced variants due they were so specific to some components, these are:
 
-For external use: `Open Sans` and `Montserrat` families have been replaced by `Inter` and `Overpass Mono`, you have an example of this in the [`preview-head.html`](https://github.com/CartoDB/carto-react/blob/master/packages/react-ui/storybook/.storybook/preview-head.html) file.
+- `charts`: replaced by `theme.palette.overline` + `weight='strong'`
 
-We have a `Typography` component that uses `Mui Typography` and extends it with some useful props:
+### Font families
 
-- weight
-- italic
+For external use: `Open Sans` and `Montserrat` families have been replaced by `Inter` and `Overpass Mono`, you have an example of this in the [`preview-head.html`](https://github.com/CartoDB/carto-react/blob/master/packages/react-ui/storybook/.storybook/preview-head.html) file.
 
-This way we can be more flexible regarding text styles without adding too many variants to the Mui component.
+## Colors
 
-In short, instead of Mui Typography, the component you should use to add text is this one:
-`react-ui/src/components/atoms/Typography`
+### New colors
 
-For external use: `import { Typography } from '@carto/react-ui';`.
+- `default` variant: new set of neutral colors. Use it instead of `grey palette`.
+- `brand palette` with custom CARTO colors for branding.
+- We also have a set of `shade` colors (with transparency):
+  - `black`
+  - `white`
 
-## Colors
+### Deleted colors
 
 Some keys have been removed from [color palette](https://github.com/CartoDB/carto-react/tree/master/packages/react-ui/src/theme) due they are unused:
 
@@ -89,18 +103,13 @@ Some keys have been removed from [color palette](https://github.com/CartoDB/cart
 - focusOpacity
 - other, all removed but divider, which is moved to first level
 
-Some others have been moved or replaced because they aren't native MUI keys and are so specific to some components, these are:
-
-- charts (replaced by `theme.palette.black[%]`)
-
-`grey palette` is not used to design (and therefore not for style) components directly. We have a set of neutral colors to use in the custom `default` variant.
-
-We also have a set of `shade` colors (with transparency):
+### Replaced colors
 
-- black
-- white
+Some others have been moved or replaced because they aren't native MUI keys and are so specific to some components, these are:
 
-Important: `primary.relatedLight` and `secondary.relatedLight` has to be replaced by `primary.background` and `secondary.background`.
+- `charts`: replaced by `theme.palette.black[%]`
+- `primary.relatedLight`: replaced by `primary.background`
+- `secondary.relatedLight`: replaced by `secondary.background`.
 
 ## Spacing
 
@@ -122,9 +131,33 @@ Design is restringed to a few specific values for shadows, which are:
 
 `0, 1, 2, 4, 6, 8, 16, 24`.
 
+## Tooltip
+
+Now, by default is placed `top` and has an `arrow` indicator, so you don't need to specify these properties anymore.
+
+We have a new component for building data structures within Tooltips, `TooltipData`.
+
 # Components
 
-## Button
+## Mui components replacement
+
+These components should be imported from carto-react library instead of Mui, as they replace the Mui components extending their functionality to meet with design criteria.
+
+### Typography
+
+We have a `Typography` component that uses `Mui Typography` and extends it with some styling props:
+
+- weight
+- italic
+
+This way we can be more flexible regarding text styles without adding too many variants to the Mui component.
+
+In short, instead of Mui Typography, the component you should use to add text is this one:
+`react-ui/src/components/atoms/Typography`
+
+For external use: `import { Typography } from '@carto/react-ui';`.
+
+### Button
 
 We have a `Button` component that uses `Mui Button` and wraps its children in `Typography` to meet with the designed behavior (text overflow case).
 
@@ -133,56 +166,113 @@ So, instead of Mui Button, the component you should use to create buttons is thi
 
 For external use: `import { Button } from '@carto/react-ui';`.
 
-## Tooltip
+### AppBar
 
-Now, by default is placed `top` and has an `arrow` indicator, so you don't need to specify these properties anymore.
+We have a custom component to build the basic structure and styles on top of AppBar Mui component.
 
-We have a new component for building data structures within Tooltips, `TooltipData`.
+This component normalize size and position of common elements like:
+
+- Logo
+- Texts
+- Avatar
+- Burger menu icon
+
+Use `<AppBar /> ` from: `react-ui/src/components/organisms/AppBar`
+
+For external use: `import { AppBar } from '@carto/react-ui';`.
+
+### Avatar
+
+We have an `Avatar` component that uses `Mui Avatar` and extends it with a new styling prop:
+
+- size
+
+This component normalize `size` and allow us to use only the 4 sizes defined by the design system:
+
+- large
+- medium
+- small
+- xsmall
+
+Use `<Avatar /> ` from: `react-ui/src/components/molecules/Avatar`
+
+For external use: `import { Avatar } from '@carto/react-ui';`.
+
+## New components
+
+These components provide extra functionality to meet the design specs, but they don't exist in Mui library.
 
-## Password Input Field
+### PasswordField
 
-We have a custom component to build the show / hide content logic on top of TextField Mui component.
+This component build the show / hide content logic on top of TextField Mui component.
 
-Instead of `<TextField type='password' /> ` you can use:
+Instead of `<TextField type='password' /> ` you should use:
 `react-ui/src/components/atoms/PasswordField`
 
 For external use: `import { PasswordField } from '@carto/react-ui';`.
 
-## Select Field
+### SelectField
 
-We have a custom component to build the `placeholder` and `multiple selection` logic on top of TextField Mui component.
+This component add the `placeholder` and `multiple selection` logic on top of TextField Mui component.
 
-Instead of `<TextField select /> ` or `<Select />` you can use:
+Instead of `<TextField select /> ` or `<Select />` you should use:
 `react-ui/src/components/atoms/SelectField`
 
 For external use: `import { SelectField } from '@carto/react-ui';`.
 
-## InputFile / UploadField
+### UploadField
 
 This component is used to display and input `type='file'`.
 
-We are replacing `InputFile` component by the new `UploadField`.
+We are replacing our old `InputFile` component by this new `UploadField`.
 
-Instead of `<Inputfile /> ` you can use:
+Instead of `<Inputfile /> ` you should use:
 `react-ui/src/components/molecules/UploadField`
 
 For external use: `import { UploadField } from '@carto/react-ui';`.
 
-## AppBar
+### LabelWithIndicator
 
-We have a custom component to build the basic structure and styles on top of AppBar Mui component.
+Designers had the need to mark inputs as `optional` or `required` depending on the use case. That is, in some forms, we have the optional ones marked but in others the required ones.
 
-This component normalize size and position of common elements like:
+Mui only provides a `required` bool prop to mark an input as mandatory. When is true, add an asterisk at the end of the label and the validation logic.
 
-- logo
-- Texts
-- Avatar
-- Burger menu icon
+We removed the asterisk in the theme, and handle both, required and optional indicators, with this new component. So we can use the following:
 
-You can use `<AppBar /> ` from:
-`react-ui/src/components/organisms/AppBar`
+Required
 
-For external use: `import { AppBar } from '@carto/react-ui';`.
+```
+<TextField
+  {...props}
+  label={<LabelWithIndicator label={label}  type='required' />}
+/>
+```
+
+Optional
+
+```
+<TextField
+  {...props}
+  label={<LabelWithIndicator label={label} />}
+/>
+```
+
+Use `<LabelWithIndicator /> ` from: `react-ui/src/components/atoms/Avatar`
+
+For external use: `import { LabelWithIndicator } from '@carto/react-ui';`.
+
+### AccordionGroup
+
+Component used as a container of a group of `Mui Accordions`, that also add a `variant` prop to have different styles in the group.
+
+Available variants:
+
+- Standard (default)
+- Outlined
+
+Use `<AccordionGroup /> ` from: `react-ui/src/components/molecules/AccordionGroup`
+
+For external use: `import { AccordionGroup } from '@carto/react-ui';`.
 
 # Testing