Migration guide polish and examples (#10889)

Fixes #10806

1. Added support for `<details>` toggles on markdown
2. Added support for `collabsibleTOC` pages (off by default) so you can
quickly skip to the section you need. This isn't perfect yet (doesn't
auto open when linking directly to an anchor) but is much better than
what we currently have
3. Organized v11 to v12 styleguide into consistent steps
4. Put regex validation, mapping tables, and examples in details toggles
to make the page less overwhelming and put migration commands at the
forefront
5. Added introduction, glossary, and generalized the migration workflow
section. Put these at the top to introduce builders to the migration
6. Added descriptive titles to all component migrations naming what they
do
7. Added examples to each component migration and removed them from the
"Whats new" page
8. Added regex validation snippets to all component migrations
9. Added alert text for stepped migrations that have to be run in order
10. Cleaned up copy and overall improved migration experience giving
more context on how and why we are running the migrations. Aimed to make
it clear enough that an intern could run a migration on their code base
11. Add padding to code blocks


![toc-demo](https://github.com/Shopify/polaris/assets/20652326/c1b012b6-b576-405f-a69e-f7cc085d66f2)

![Screen Recording 2023-10-05 at 3 09 18
PM](https://github.com/Shopify/polaris/assets/20652326/4999bcbe-960b-4718-ba73-04963eeed302)

---------

Co-authored-by: Lo Kim <[email protected]>

documentation/guides/README.md

@@ -0,0 +1,3 @@
+# Guides
+
+Migration guides for upgrading from v11 to v12 and onwards are hosted on our documentation site at https://polaris.shopify.com/version-guides.

polaris.shopify.com/content/whats-new/version-12.md

@@ -68,152 +68,14 @@ Semantic tokens are references to base values that are used in specific contexts
 
 ### Component API simplification
 
-The version 12 breaking component changes aim to simplify inconsistent and complicated component APIs.
-
-Note: the below examples are for illustrative purposes only. For a comprehensive list on all component changes and how to migrate from v11's component APIs, check out the [migration guide](/version-guides/migrating-from-v11-to-v12#component-migrations).
-
-#### Logical properties rename
-
-Directional components now use `Inline` and `Block` which are defined by [CSS logical properties](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_logical_properties_and_values). This is to be consistent with other Polaris component APIs as well as wider web conventions.
-
-```diff
-- <HorizontalStack />
-+ <InlineStack />
-- <VerticalStack />
-+ <BlockStack />
-- <HorizontalGrid />
-+ <InlineGrid />
-```
-
-#### Consolidate color changes to `tone`
-
-Renaming color control props to `tone` creates a consistent API across components.
-
-```diff
-- <Banner status="success" />
-+ <Banner tone="success" />
-
-- <Icon color="success" />
-- <Icon color="warning" />
-- <Icon color="highlight" />
-+ <Icon tone="success" />
-+ <Icon tone="caution" />
-+ <Icon tone="info" />
-
-- <Text color="success" />
-- <Text color="warning" />
-+ <Text tone="success" />
-+ <Text tone="caution" />
-
-- <Badge status="success" statusAndProgressLabelOverride="My string" />
-+ <Badge tone="success" toneAndProgressLabelOverride="My string" />
-
-- <Button destructive />
-+ <Button variant="primary" tone="critical" />
-- <Button primarySuccess />
-+ <Button variant="primary" tone="success" />
-- <Button destructive outline />
-+ <Button tone="critical" />
-- <Button destructive plain />
-+ <Button variant="plain" tone="critical" />
-
-- <IndexTable.Row status="success" />
-+ <IndexTable.Row tone="success" />
-```
-
-#### Consolidate boolean props to `variant`
-
-The logical combinations of boolean props can get confusing. A single `variant` prop is now used to control rendering different component styles.
-
-```diff
-- <ButtonGroup segmented />
-+ <ButtonGroup variant="segmented" />
-
-- <TextField borderless />
-+ <TextField variant="borderless" />
-
-- <Layout.Section oneThird>
-- <Layout.Section oneHalf>
-- <Layout.Section fullWidth>
-- <Layout.Section secondary>
-+ <Layout.Section variant="oneThird">
-+ <Layout.Section variant="oneHalf">
-+ <Layout.Section variant="fullWidth">
-+ <Layout.Section variant="oneThird">
-
-- <Button plain />
-+ <Button variant="plain" />
-- <Button primary />
-+ <Button variant="primary" />
-- <Button destructive />
-+ <Button variant="primary" tone="critical" />
-- <Button primarySuccess />
-+ <Button variant="primary" tone="success" />
-- <Button destructive plain />
-+ <Button variant="plain" tone="critical" />
-
-- <Modal small />
-- <Modal large />
-- <Modal fullScreen />
-+ <Modal size="small" />
-+ <Modal size="large" />
-+ <Modal size="fullScreen" />
-```
-
-#### Rename `spacing` to `gap`
-
-Renaming space control props to `gap` creates a consistent API across components.
-
-```diff
-- <ButtonGroup spacing="tight" />
-+ <ButtonGroup gap="tight" />
-
-- <List spacing="loose" />
-+ <List gap="loose" />
-
-- <DescriptionList spacing="loose" />
-+ <DescriptionList gap="loose" />
-```
-
-#### Other prop renames
-
-```diff
-- <Box borderRadiusEndStart="2" borderRadiusEndEnd="2" borderRadiusStartStart="2" borderRadiusStartEnd="2" />
-+ <Box borderEndStartRadius="2" borderEndEndRadius="2" borderStartStartRadius="2" borderStartEndRadius="2" />
-
-- <Avatar size="extraSmall" />
-- <Avatar size="small" />
-- <Avatar size="medium" />
-- <Avatar size="large" />
-- <Avatar size="xl-experimental" />
-- <Avatar size="2xl-experimental" />
-+ <Avatar size="xs" />
-+ <Avatar size="sm" />
-+ <Avatar size="md" />
-+ <Avatar size="lg" />
-+ <Avatar size="xl" />
-+ <Avatar size="xl" />
-```
-
-#### Prop deprecations
-
-```diff
-- <Icon backdrop />
-+ <Box padding="1" width="28px" borderRadius="full">
-+   <Icon />
-+ </Box>
-
-- <Button connectedDisclosure />
-+ <ButtonGroup variant="segmented">
-+   <Button />
-+   <Button icon={ChevronDownMinor} />
-+ </ButtonGroup>
-
-- <Button monochrome />
-- <Button outline />
-+ <Button />
-+ <Button />
-```
+The version 12 breaking component changes aim to simplify inconsistent and complicated component APIs. For a comprehensive list on all component changes and how to migrate from v11's component APIs, check out the [migration guide](/version-guides/migrating-from-v11-to-v12#component-migrations).
+
+**At a high level the API changes aimed to simplify, consolidate, and align by:**
+
+- Renaming directional components to use `Inline` and `Block` which are defined by [CSS logical properties](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_logical_properties_and_values)
+- Renaming border radius properties to align with [CSS border radius constituent properties](https://developer.mozilla.org/en-US/docs/Web/CSS/border-radius#constituent_properties)
+- Renaming various color control props to `tone` and space control props to `gap`. This creates more consistent APIs across components
+- Consolidating boolean props to a single `variant` prop on various components to make logical combinations more intentional
 
 ## Resources
 

polaris.shopify.com/pages/[...slug].tsx

@@ -21,6 +21,7 @@ interface Props {
   editPageLinkPath: string;
   isContentPage: boolean;
   showTOC?: boolean;
+  collapsibleTOC?: boolean;
 }
 
 interface SortedRichCardGridProps extends RichCardGridProps {
@@ -89,6 +90,7 @@ const CatchAllTemplate = ({
   editPageLinkPath,
   isContentPage,
   showTOC,
+  collapsibleTOC,
 }: InferGetStaticPropsType<typeof getStaticProps>) => {
   const {title, noIndex = false} = mdx.frontmatter;
 
@@ -97,6 +99,7 @@ const CatchAllTemplate = ({
       editPageLinkPath={editPageLinkPath}
       isContentPage={isContentPage}
       showTOC={showTOC || isContentPage}
+      collapsibleTOC={collapsibleTOC}
     >
       <PageMeta title={title} description={seoDescription} noIndex={noIndex} />
       <Markdown
@@ -315,6 +318,7 @@ export const getStaticProps: GetStaticProps<Props, {slug: string[]}> = async ({
     editPageLinkPath,
     isContentPage: !pathIsDirectory,
     showTOC: mdx.frontmatter.showTOC || false,
+    collapsibleTOC: mdx.frontmatter.collapsibleTOC || false,
   };
 
   return {props};

polaris.shopify.com/src/components/Code/Code.module.scss

@@ -7,6 +7,7 @@
   background: var(--surface);
   color: var(--text-strong);
   border: var(--border);
+  margin: 1rem 0;
 }
 
 .TopBar {

polaris.shopify.com/src/components/CollapsibleDetails/index.tsx

@@ -0,0 +1,51 @@
+import React, {useState} from 'react';
+import {motion, AnimatePresence} from 'framer-motion';
+import Icon from '../Icon';
+import {CaretDownMinor} from '@shopify/polaris-icons';
+
+export interface CollasibleDetailsProps {
+  summary?: string | React.ReactNode;
+}
+export function CollapsibleDetails({
+  children,
+  summary,
+}: React.PropsWithChildren<CollasibleDetailsProps>) {
+  const [isOpen, setIsOpen] = useState(false);
+
+  const toggleOpen = () => {
+    setIsOpen(!isOpen);
+  };
+
+  return (
+    <div>
+      <motion.summary
+        style={{display: 'flex', margin: '0.5rem 0', cursor: 'pointer'}}
+        onClick={toggleOpen}
+        initial={false}
+      >
+        <motion.span
+          style={{display: 'flex', maxHeight: '20px'}}
+          initial={{rotate: -90}}
+          animate={{rotate: isOpen ? 0 : -90}}
+          exit={{rotate: -90}}
+          transition={{ease: 'easeInOut', duration: 0.15}}
+        >
+          <Icon source={CaretDownMinor} />
+        </motion.span>
+        {summary}
+      </motion.summary>
+      <AnimatePresence>
+        {isOpen && (
+          <motion.div
+            initial={{opacity: 0, height: 0}}
+            animate={{opacity: 1, scale: 1, height: 'auto'}}
+            exit={{opacity: 0, height: 0}}
+            transition={{ease: 'easeInOut', duration: 0.15}}
+          >
+            {children}
+          </motion.div>
+        )}
+      </AnimatePresence>
+    </div>
+  );
+}

polaris.shopify.com/src/components/Markdown/Markdown.tsx

@@ -32,6 +32,7 @@ import Icon from '../Icon';
 import {FeaturedCardGrid} from '../FeaturedCardGrid';
 import {useCopyToClipboard} from '../../utils/hooks';
 import {Colors} from './components/Colors';
+import {CollapsibleDetails} from '../../components/CollapsibleDetails';
 
 const CodeVisibilityContext = createContext<
   [
@@ -247,6 +248,8 @@ function Markdown<
         Subnav,
         RichCardGrid,
         Colors,
+        CollapsibleDetails,
+        Code,
         Tip: ({children}) => (
           <div className="tip-banner">
             <div className="tip-banner__header">

polaris.shopify.com/src/components/Page/Page.module.scss

@@ -68,7 +68,6 @@
   padding: var(--p-space-400) var(--p-space-200) var(--p-space-200);
   width: var(--toc-width);
   overscroll-behavior: contain;
-  overflow: auto;
   border: 1.5px solid var(--border-color);
   border-radius: var(--p-border-radius-300);
 

polaris.shopify.com/src/components/Page/Page.tsx

@@ -17,13 +17,15 @@ interface Props {
    * or hide the TOC, use showTOC */
   isContentPage?: boolean;
   showTOC?: boolean;
+  collapsibleTOC?: boolean;
   children: React.ReactNode;
 }
 
 function Layout({
   title,
   isContentPage = false,
   showTOC = isContentPage,
+  collapsibleTOC = false,
   editPageLinkPath,
   children,
 }: Props) {
@@ -63,7 +65,7 @@ function Layout({
       </Box>
       {showTOC && (
         <div className={styles.TOCWrapper}>
-          <TOC items={tocItems} />
+          <TOC items={tocItems} collapsibleTOC={collapsibleTOC} />
         </div>
       )}
     </Container>

polaris.shopify.com/src/components/TOC/TOC.module.scss

@@ -25,15 +25,20 @@
 }
 
 .Link {
-  color: var(--text-strong);
-  display: block;
-  font-size: var(--p-font-size-325);
-  font-weight: var(--p-font-weight-regular);
-  line-height: var(--p-font-line-height-500);
-  overflow: hidden;
   padding: var(--p-space-100) var(--p-space-200);
-  text-overflow: ellipsis;
-  white-space: pre;
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+
+  span {
+    color: var(--text-strong);
+    font-size: var(--p-font-size-325);
+    font-weight: var(--p-font-weight-regular);
+    line-height: var(--p-font-line-height-500);
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: pre;
+  }
 
   &:hover {
     background-color: var(--surface-active);
@@ -43,6 +48,37 @@
   &.active {
     background-color: var(--surface-active);
     border-radius: var(--p-border-radius-200);
-    font-weight: var(--p-font-weight-semibold);
+
+    span {
+      font-weight: var(--p-font-weight-semibold);
+    }
+  }
+}
+
+.TOCItemMaxWidth {
+  max-width: calc(var(--toc-width) * 0.75);
+}
+
+.Toggle {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 24px;
+  height: 24px;
+  border-radius: 100%;
+  background-color: transparent;
+  background-image: url(/images/PlusMinor.svg);
+  background-repeat: no-repeat;
+  background-position: center center;
+  background-size: 12px 12px;
+  opacity: 0.66;
+
+  &:hover {
+    opacity: 1;
+    background-color: var(--surface-subdued);
+  }
+
+  &[aria-expanded='true'] {
+    background-image: url(/images/MinusMinor.svg);
   }
 }