[Layout foundations] Deprecate grid component (#8418)

Closes: #7741

---------

Co-authored-by: jjgali <77791660+jjgali@users.noreply.github.com>

Author: kyledurand

.changeset/stale-maps-ring.md

@@ -0,0 +1,7 @@
+---
+'@shopify/polaris': minor
+'polaris.shopify.com': patch
+---
+
+Deprecated Grid component
+Update documentation for deprecated components

polaris-react/src/components/Grid/Grid.tsx

@@ -1,5 +1,6 @@
-import React from 'react';
+import React, {useEffect} from 'react';
 
+// eslint-disable-next-line import/no-deprecated
 import {Cell} from './components';
 import styles from './Grid.scss';
 
@@ -26,12 +27,9 @@ export interface GridProps {
   gap?: Gap;
   children?: React.ReactNode;
 }
-/** **Experimental!**
- * This component is in alpha. Use with caution.
- * 6 column default for xs, sm, and md breakpoints.
- * 12 columns for lg, and xl.
- */
+/** @deprecated Use `Columns` instead or a combination of layout primitives (`Columns`, `Inline`, and `AlphaStack`) */
 export const Grid: React.FunctionComponent<GridProps> & {
+  // eslint-disable-next-line import/no-deprecated
   Cell: typeof Cell;
 } = function Grid({gap, areas, children, columns}: GridProps) {
   const style = {
@@ -52,6 +50,15 @@ export const Grid: React.FunctionComponent<GridProps> & {
     '--pc-grid-areas-xl': formatAreas(areas?.xl),
   } as React.CSSProperties;
 
+  useEffect(() => {
+    if (process.env.NODE_ENV === 'development') {
+      // eslint-disable-next-line no-console
+      console.warn(
+        'Deprecation: <Grid /> is deprecated. This component will be removed in a future major version of Polaris. Use <Columns /> instead or a combination of <Columns />, <Inline />, and <AlphaStack />',
+      );
+    }
+  }, []);
+
   return (
     <div className={styles.Grid} style={style}>
       {children}
@@ -64,4 +71,5 @@ export function formatAreas(areas?: string[]) {
   return `'${areas?.join(`' '`)}'`;
 }
 
+// eslint-disable-next-line import/no-deprecated
 Grid.Cell = Cell;

polaris-react/src/components/Grid/components/Cell/Cell.tsx

@@ -30,7 +30,7 @@ export interface CellProps {
   row?: Cell;
   children?: React.ReactNode;
 }
-
+/** @deprecated Use `Columns` instead or a combination of layout primitives (`Columns`, `Inline`, and `AlphaStack`) */
 export function Cell({
   area: gridArea,
   column,

polaris-react/src/components/Grid/components/Cell/tests/Cell.test.tsx

@@ -1,6 +1,7 @@
 import React from 'react';
 import {mountWithApp} from 'tests/utilities';
 
+// eslint-disable-next-line import/no-deprecated
 import {Cell} from '../Cell';
 
 describe('<Cell />', () => {

polaris-react/src/components/Grid/tests/Grid.test.tsx

@@ -2,6 +2,7 @@ import React from 'react';
 import {matchMedia, timer} from '@shopify/jest-dom-mocks';
 import {mountWithApp} from 'tests/utilities';
 
+// eslint-disable-next-line import/no-deprecated
 import {formatAreas, Grid} from '../Grid';
 
 describe('<Grid />', () => {

polaris.shopify.com/content/components/layout-and-structure/grid.md renamed to polaris.shopify.com/content/components/deprecated/grid.md

@@ -1,7 +1,7 @@
 ---
 title: Grid
 description: Create complex layouts based on [CSS Grid](https://developer.mozilla.org/en-US/docs/Web/CSS/grid).
-category: Layout and structure
+category: Deprecated
 keywords:
   - one column
   - two column
@@ -14,8 +14,10 @@ keywords:
   - full width containers
   - css grid
 status:
-  value: Alpha
-  message: This component is slated to be deprecated in v11. Please consider using alternate layout primitive components such as Columns, Inline, or AlphaStack.
+  value: Deprecated
+  message: >-
+    Grid was built prior to layout primitives like columns, inline, and alpha stack. Comparatively, grid is difficult to learn, document, and understand its usage in a codebase.
+    The new layout primitives should be used in combination to achieve similar results to grid.
 examples:
   - fileName: grid-two-column.tsx
     title: Two column

polaris.shopify.com/content/components/deprecated/index.md

@@ -2,4 +2,6 @@
 title: Deprecated
 expanded: true
 order: 12
+description: >-
+  Deprecated components will be removed in future major versions of Polaris. These components could be deprecated for a [number of reasons](https://polaris.shopify.com/getting-started/components-lifecycle#requirements-for-deprecation) and should be avoided. These components will show warnings in the component file and provide details for alternative usage. For more information, check out the [component lifecycle](https://polaris.shopify.com/getting-started/components-lifecycle#deprecated).
 ---

polaris.shopify.com/next.config.js

@@ -196,6 +196,11 @@ const deprecated = [
     destination: '/components/deprecated/display-text',
     permanent: false,
   },
+  {
+    source: '/components/grid',
+    destination: '/components/deprecated/grid',
+    permanent: false,
+  },
   {
     source: '/components/heading',
     destination: '/components/deprecated/heading',
@@ -360,11 +365,6 @@ const layoutAndStructure = [
     destination: '/components/layout-and-structure/form-layout',
     permanent: false,
   },
-  {
-    source: '/components/grid',
-    destination: '/components/layout-and-structure/grid',
-    permanent: false,
-  },
   {
     source: '/components/inline',
     destination: '/components/layout-and-structure/inline',

polaris.shopify.com/pages/components/[group]/index.tsx

@@ -127,9 +127,12 @@ export default function GroupPage({
       />
       <AlphaStack gap="16">
         <AlphaStack gap="4">
-          <Longform firstParagraphIsLede>
-            <p>{frontMatter?.description}</p>
-          </Longform>
+          {frontMatter?.description && (
+            <Longform firstParagraphIsLede>
+              <Markdown>{frontMatter?.description}</Markdown>
+            </Longform>
+          )}
+
           {groupsMarkup || componentsFromPaths}
         </AlphaStack>
         {relatedResourcesMarkup}