docs: add migration guide to v2 (#4076)

Semantic-Org · Sep 29, 2020 · 57dd7dd · 57dd7dd
1 parent f9e90ff
commit 57dd7dd
Show file tree

Hide file tree

Showing 7 changed files with 105 additions and 5 deletions.
diff --git a/docs/public/style.css b/docs/public/style.css
@@ -12,7 +12,7 @@ body {
 }
 
 blockquote {
-  border-left: 3px solid rgba(34, 36, 38, .15);
+  border-left: 3px solid rgba(34, 36, 38, 0.15);
   margin-left: 0;
   padding-left: 10px;
   font-style: italic;
@@ -43,20 +43,20 @@ pre {
   margin: 0;
 }
 
-code:not([class*="language-"]) {
+code:not([class*='language-']) {
   font-size: 87.5%;
   background-color: rgba(0, 0, 0, 0.04);
   border-radius: 3px;
   white-space: pre;
   display: inline-block;
 }
 
-code:not([class*="language-"])::before {
+code:not([class*='language-'])::before {
   letter-spacing: -0.2em;
   content: '\00a0';
 }
 
-code:not([class*="language-"])::after {
+code:not([class*='language-'])::after {
   letter-spacing: -0.2em;
   content: '\00a0';
 }
@@ -138,3 +138,13 @@ code:not([class*="language-"])::after {
 .carbon-poweredby:hover {
   color: #ddd;
 }
+
+/* --- */
+
+.token.deleted {
+  color: #e2777a;
+}
+
+.token.inserted {
+  color: #7ec699;
+}
diff --git a/docs/src/components/CodeSnippet/CodeSnippet.js b/docs/src/components/CodeSnippet/CodeSnippet.js
@@ -5,6 +5,7 @@ import React from 'react'
 
 // Order of PrismJS imports there is sensitive
 import 'prismjs/components/prism-clike'
+import 'prismjs/components/prism-diff'
 import 'prismjs/components/prism-json'
 import 'prismjs/components/prism-markup'
 import 'prismjs/components/prism-bash'
@@ -23,6 +24,7 @@ const normalizeToString = (value) => {
 
 const formatters = {
   bash: (val = '') => val.replace(/^[\w]/gm, '$$  $&'),
+  diff: (val) => val,
   json: (val) => val,
   js: (val = '') => val,
   jsx: (val = '') => val,

diff --git a/docs/src/components/Document.js b/docs/src/components/Document.js
@@ -10,7 +10,6 @@ const Document = ({ Body, children, Head, Html, siteData: { dev, versions } }) =
       <meta name='viewport' content='width=device-width, initial-scale=1, shrink-to-fit=no' />
 
       <link rel='shortcut icon' type='image/x-icon' href='/logo.png' />
-      <link rel='stylesheet' href={`/style.css?${versions.suir}`} />
       <link
         rel='stylesheet'
         href={`https://cdn.jsdelivr.net/npm/semantic-ui@${versions.sui}/dist/semantic.min.css`}
@@ -52,6 +51,8 @@ const Document = ({ Body, children, Head, Html, siteData: { dev, versions } }) =
           versions.react
         }/umd/react-dom-server.browser${dev ? '.development' : '.production.min'}.js`}
       />
+
+      <link rel='stylesheet' href={`/style.css?${versions.suir}`} />
     </Head>
     <Body>{children}</Body>
   </Html>

diff --git a/docs/src/components/DocumentationPage/components.js b/docs/src/components/DocumentationPage/components.js
@@ -23,3 +23,5 @@ export const code = ({ className, children, fitted, formattable, label }) => (
 export const h1 = ({ children }) => <Header as='h1' content={children} textAlign='center' />
 
 export const h2 = ({ children }) => <Header as='h2' content={children} dividing />
+
+export const h3 = ({ children }) => <Header as='h3' content={children} />
diff --git a/docs/src/components/Sidebar/Sidebar.js b/docs/src/components/Sidebar/Sidebar.js
@@ -223,6 +223,9 @@ class Sidebar extends Component {
                 <Menu.Item as={Link} exact to='/prototypes' activeClassName='active'>
                   Prototypes
                 </Menu.Item>
+                <Menu.Item as={Link} exact to='/migration-guide' activeClassName='active'>
+                  Migration guide to v2
+                </Menu.Item>
               </Menu.Menu>
             </Menu.Item>
             <Menu.Item fitted>

diff --git a/docs/src/pages/MigrationGuide.mdx b/docs/src/pages/MigrationGuide.mdx
@@ -0,0 +1,81 @@
+export const meta = {
+  title: 'Migration Guide',
+  prevPage: { title: 'Prototypes', href: '/prototypes' },
+}
+
+This is a reference for upgrading your application to v2 of Semantic UI React. While there's a lot covered here, you probably won't need to do everything for your app.
+
+## Upgrade of `react-popper` for `Popup`
+
+_Popper.js v1 is out of date, v2 was released in Dec 2019, time to upgrade 🚀_
+
+### `offset` can't be specified as string anymore
+
+Previously it was possible to pass different units to the offset prop as units. This behavior was changed and `offset` accepts a tuple or a function. Examples in our docs were also updated.
+
+```diff
+ <>
+-  <Popup offset="50px" />
++  <Popup offset={[50, 0]} />
+   <br />
+-  <Popup offset="-100%p" />
++  <Popup offset={({ popper }) => [-popper.width, 0]} />
+ </>
+```
+
+### `popperModifiers` should be defined as array now
+
+The `popperModifiers` prop should be defined as an array with changed format (see [Popper docs](https://popper.js.org/docs/v2/migration-guide/#10-update-modifiers)).
+
+```diff
+-<Popup popperModifiers={{ preventOverflow: { padding: 0 } }} />
++<Popup popperModifiers={[{ name: 'preventOverflow', options: { padding: 0 } }]} />
+```
+
+## `Responsive` component was removed
+
+`Responsive` component was deprecated in 1.1.0. There are two main reasons for the removal: there is no connection between breakpoints and pure SSR (server side rendering) support.
+
+[@artsy/fresnel](https://github.com/artsy/fresnel) was proposed as a replacement as it properly handles SSR scenarios.
+
+```diff
++import { createMedia } from "@artsy/fresnel";
+import React from "react";
+-import { Responsive, Segment } from "semantic-ui-react";
++import { Segment } from "semantic-ui-react";
+
++const AppMedia = createMedia({
++  breakpoints: {
++    mobile: 320,
++    tablet: 768,
++    computer: 992,
++    largeScreen: 1200,
++    widescreen: 1920
++  }
++});
++const mediaStyles = AppMedia.createMediaStyle();
++const { Media, MediaContextProvider } = AppMedia;
+
+-const App = () => (
+-  <Responsive as={Segment} {...Responsive.onlyMobile}>
+-    Mobile
+-  </Responsive>
+-)
++const App = () => (
++  <>
++    <style>{mediaStyles}</style>
++    <MediaContextProvider>
++      <Segment as={Media} at="mobile">
++        Mobile
++      </Segment>
++    </MediaContextProvider>
++  </>
++);
+```
+
+The full migration guide is available in [Semantic-Org/Semantic-UI-React#4008](https://github.com/Semantic-Org/Semantic-UI-React/pull/4008), it contains more detailed explanation and examples for Next.js & Gatsby.
+
+## `MountNode` component was removed
+
+`MountNode` component was deprecated in 1.1.0. The main reason for the removal is that the component should not be a part of the public API as it solves our specific issue with the `Modal` component.
+Additional details are available in [Semantic-Org/Semantic-UI-React#4027](https://github.com/Semantic-Org/Semantic-UI-React/pull/4027).
diff --git a/docs/src/pages/Prototypes.mdx b/docs/src/pages/Prototypes.mdx
@@ -3,6 +3,7 @@ import { Button, Card, Header, Image } from 'semantic-ui-react'
 export const meta = {
   title: 'Prototypes',
   prevPage: { title: 'Layout examples', href: '/layouts' },
+  nextPage: { title: 'Migration Guide', href: '/migration-guide' },
 }
 
 <Header as='h2' content='Integrations' subheader='Examples of integrations with other libraries' />
Original file line number	Diff line number	Diff line change
Expand Up		@@ -23,3 +23,5 @@ export const code = ({ className, children, fitted, formattable, label }) => (
		export const h1 = ({ children }) => <Header as='h1' content={children} textAlign='center' />

		export const h2 = ({ children }) => <Header as='h2' content={children} dividing />

		export const h3 = ({ children }) => <Header as='h3' content={children} />