[Layout foundations] Deprecate Stack and subcomponents

.changeset/nice-points-confess.md

@@ -0,0 +1,6 @@
+---
+'@shopify/polaris': minor
+'polaris.shopify.com': patch
+---
+
+Deprecated `Stack` and `Stack.Item` and updated documentation on style guide

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

@@ -3,6 +3,7 @@ import React, {memo, NamedExoticComponent} from 'react';
 import {classNames, variationName} from '../../utilities/css';
 import {elementChildren, wrapWithComponent} from '../../utilities/components';
 
+// eslint-disable-next-line import/no-deprecated
 import {Item} from './components';
 import styles from './Stack.scss';
 
@@ -39,6 +40,7 @@ export interface StackProps {
   distribution?: Distribution;
 }
 
+/** @deprecated Use LegacyStack or AlphaStack instead. */
 export const Stack = memo(function Stack({
   children,
   vertical,
@@ -47,6 +49,13 @@ export const Stack = memo(function Stack({
   alignment,
   wrap,
 }: StackProps) {
+  if (process.env.NODE_ENV === 'development') {
+    // eslint-disable-next-line no-console
+    console.warn(
+      'Deprecation: <Stack /> is deprecated. This component will be removed in a future major version of Polaris. Use <LegacyStack /> or <AlphaStack /> instead.',
+    );
+  }
+
   const className = classNames(
     styles.Stack,
     vertical && styles.vertical,
@@ -58,12 +67,15 @@ export const Stack = memo(function Stack({
 
   const itemMarkup = elementChildren(children).map((child, index) => {
     const props = {key: index};
+    // eslint-disable-next-line import/no-deprecated
     return wrapWithComponent(child, Item, props);
   });
 
   return <div className={className}>{itemMarkup}</div>;
 }) as NamedExoticComponent<StackProps> & {
+  // eslint-disable-next-line import/no-deprecated
   Item: typeof Item;
 };
 
+// eslint-disable-next-line import/no-deprecated
 Stack.Item = Item;

polaris-react/src/components/Stack/components/Item/Item.tsx

@@ -13,7 +13,15 @@ export interface ItemProps {
    */
 }
 
+/** @deprecated Use LegacyStack or AlphaStack instead. */
 export function Item({children, fill}: ItemProps) {
+  if (process.env.NODE_ENV === 'development') {
+    // eslint-disable-next-line no-console
+    console.warn(
+      'Deprecation: <Stack /> is deprecated. This component will be removed in a future major version of Polaris. Use <LegacyStack /> or <AlphaStack /> instead.',
+    );
+  }
+
   const className = classNames(styles.Item, fill && styles['Item-fill']);
 
   return <div className={className}>{children}</div>;

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

@@ -1,6 +1,7 @@
 import React from 'react';
 import {mountWithApp} from 'tests/utilities';
 
+// eslint-disable-next-line import/no-deprecated
 import {Stack} from '../Stack';
 
 describe('<Stack />', () => {
@@ -9,6 +10,7 @@ describe('<Stack />', () => {
   it('renders its children', () => {
     const stack = mountWithApp(<Stack>{renderChildren()}</Stack>);
 
+    // eslint-disable-next-line import/no-deprecated
     expect(stack).toContainReactComponentTimes(Stack.Item, 2);
   });
 });

polaris.shopify.com/content/components/layout-and-structure/stack.md → polaris.shopify.com/content/components/deprecated/stack.md

@@ -1,7 +1,7 @@
 ---
 title: Stack
 description: Use to lay out a horizontal row of components or to achieve no-fuss vertical centering. A stack is made of flexible items that wrap each of the stack’s children. Options provide control of the wrapping, spacing, and relative size of the items in the stack.
-category: Layout and structure
+category: Deprecated
 keywords:
   - rows
   - vertical centering
@@ -17,6 +17,11 @@ keywords:
   - right-aligned stack
   - stack layout
   - layout
+status:
+  value: Deprecated
+  message: >-
+    Stack was built prior to layout primitives like box, inline, and alpha stack.
+    The new layout primitives can be used in combination to achieve similar results to stack, or the existing legacy stack.
 examples:
   - fileName: stack-default.tsx
     title: Default

polaris.shopify.com/next.config.js

@@ -211,6 +211,11 @@ const deprecated = [
     destination: '/components/deprecated/sheet',
     permanent: false,
   },
+  {
+    source: '/components/stack',
+    destination: '/components/deprecated/stack',
+    permanent: false,
+  },
   {
     source: '/components/subheading',
     destination: '/components/deprecated/subheading',
@@ -340,11 +345,6 @@ const layoutAndStructure = [
     destination: '/components/layout-and-structure/alpha-card',
     permanent: false,
   },
-  {
-    source: '/components/structure/stack',
-    destination: '/components/layout-and-structure/alpha-stack',
-    permanent: false,
-  },
   {
     source: '/components/alpha-stack',
     destination: '/components/layout-and-structure/alpha-stack',