Migration guide polish and examples

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);
   }
 }