Update AlphaStack (#7429)

### WHY are these changes introduced?

Through the rebuilding of `ChoiceList`
(#7354) I have found there are
a few updates that would make `AlphaStack` more flexible.

### WHAT is this pull request doing?

- Make `AlphaStack` polymorphic and allow it to be a `ul` or a
`fieldset` in addition to a `div`. Both those elements are used to
contain a list or group of elements that may require equal spacing. This
allows `AlphaStack` to be used in those instances while still providing
semantic markup.

- Include some reset styles for when the `ul` element is set on
`AlphaStack` to override default browser styling for `ul`. This removes
margin and padding which makes sense since spacing should be handled by
layout components. It also removes the default `ul` bullet. Is this too
opinionated? Are there use cases where `AlphaStack` would be used for
spacing items in a list with the default browser bullet?

<img width="278" alt="Screen Shot 2022-10-17 at 3 00 12 PM"
src="https://user-images.githubusercontent.com/3474483/196292082-c68d8c07-8d8b-4336-8a92-8e5363f04894.png">|<img
width="249" alt="Screen Shot 2022-10-17 at 3 00 24 PM"
src="https://user-images.githubusercontent.com/3474483/196292137-e906bc45-e7f6-4729-b2d9-09f2295380ac.png">
:----:|:----:
Default `ul` styles|Reset `ul` styles

- Update `AlphaStack` to allow responsive spacing. The `spacing` prop
can now accept an object with a breakpoint and the spacing value.

Co-authored-by: Aaron Casanova <32409546+aaronccasanova@users.noreply.github.com>
Co-authored-by: Kyle Durand <6844391+kyledurand@users.noreply.github.com>

Author: 3 people

.changeset/friendly-radios-sparkle.md

@@ -0,0 +1,5 @@
+---
+'@shopify/polaris': minor
+---
+
+Update `AlphaStack` to be polymorphic, add list reset styles and allow spacing to change based on breakpoint

polaris-react/src/components/AlphaStack/AlphaStack.scss

@@ -1,14 +1,44 @@
+@import '../../styles/common';
+
 .AlphaStack {
+  --pc-stack-spacing-xs: var(--p-space-4);
+  --pc-stack-spacing-sm: var(--pc-stack-spacing-xs);
+  --pc-stack-spacing-md: var(--pc-stack-spacing-sm);
+  --pc-stack-spacing-lg: var(--pc-stack-spacing-md);
+  --pc-stack-spacing-xl: var(--pc-stack-spacing-lg);
   display: flex;
   flex-direction: column;
   align-items: var(--pc-stack-align);
-  gap: var(--pc-stack-spacing);
+  gap: var(--pc-stack-spacing-xs);
+
+  @media #{$p-breakpoints-sm-up} {
+    gap: var(--pc-stack-spacing-sm);
+  }
+
+  @media #{$p-breakpoints-md-up} {
+    gap: var(--pc-stack-spacing-md);
+  }
+
+  @media #{$p-breakpoints-lg-up} {
+    gap: var(--pc-stack-spacing-lg);
+  }
+
+  @media #{$p-breakpoints-xl-up} {
+    gap: var(--pc-stack-spacing-xl);
+  }
 
   > * {
     max-width: 100%;
   }
 }
 
+.listReset {
+  list-style-type: none;
+  margin-block-start: 0;
+  margin-block-end: 0;
+  padding-inline-start: 0;
+}
+
 .fullWidth {
   > * {
     width: 100%;

polaris-react/src/components/AlphaStack/AlphaStack.stories.tsx

@@ -60,3 +60,14 @@ export function FullWidthChildren() {
     </AlphaStack>
   );
 }
+
+export function ResponsiveSpacing() {
+  return (
+    <AlphaStack spacing={{xs: '4', md: '10'}}>
+      <Badge>Paid</Badge>
+      <Badge>Processing</Badge>
+      <Badge>Fulfilled</Badge>
+      <Badge>Completed</Badge>
+    </AlphaStack>
+  );
+}

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

@@ -1,24 +1,36 @@
-import React from 'react';
+import React, {createElement} from 'react';
 import type {SpacingSpaceScale} from '@shopify/polaris-tokens';
 
-import {classNames} from '../../utilities/css';
+import {
+  classNames,
+  sanitizeCustomProperties,
+  getResponsiveProps,
+} from '../../utilities/css';
+import type {ResponsiveProp} from '../../utilities/css';
 
 import styles from './AlphaStack.scss';
 
 type Align = 'start' | 'end' | 'center';
 
+type Element = 'div' | 'ul' | 'ol' | 'fieldset';
+
+type Spacing = ResponsiveProp<SpacingSpaceScale>;
+
 export interface AlphaStackProps {
+  /** HTML Element type */
+  as?: Element;
   /** Elements to display inside stack */
   children?: React.ReactNode;
   /** Adjust vertical alignment of elements */
   align?: Align;
   /** Toggle elements to be full width */
   fullWidth?: boolean;
   /** Adjust spacing between elements */
-  spacing?: SpacingSpaceScale;
+  spacing?: Spacing;
 }
 
 export const AlphaStack = ({
+  as = 'div',
   children,
   align = 'start',
   fullWidth,
@@ -27,16 +39,20 @@ export const AlphaStack = ({
   const className = classNames(
     styles.AlphaStack,
     fullWidth && styles.fullWidth,
+    as === 'ul' && styles.listReset,
   );
 
   const style = {
     '--pc-stack-align': align ? `${align}` : '',
-    ...(spacing ? {'--pc-stack-spacing': `var(--p-space-${spacing})`} : {}),
+    ...getResponsiveProps('stack', 'spacing', 'space', spacing),
   } as React.CSSProperties;
 
-  return (
-    <div className={className} style={style}>
-      {children}
-    </div>
+  return createElement(
+    as,
+    {
+      className,
+      style: sanitizeCustomProperties(style),
+    },
+    children,
   );
 };

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

@@ -17,10 +17,10 @@ describe('<AlphaStack />', () => {
     const stack = mountWithApp(<AlphaStack>{children}</AlphaStack>);
 
     expect(stack).toContainReactComponent('div', {
-      style: {
+      style: expect.objectContaining({
         '--pc-stack-align': 'start',
-        '--pc-stack-spacing': 'var(--p-space-4)',
-      } as React.CSSProperties,
+        '--pc-stack-spacing-xs': 'var(--p-space-4)',
+      }) as React.CSSProperties,
     });
   });
 
@@ -32,10 +32,23 @@ describe('<AlphaStack />', () => {
     );
 
     expect(stack).toContainReactComponent('div', {
-      style: {
+      style: expect.objectContaining({
         '--pc-stack-align': 'center',
-        '--pc-stack-spacing': 'var(--p-space-10)',
-      } as React.CSSProperties,
+        '--pc-stack-spacing-xs': 'var(--p-space-10)',
+      }) as React.CSSProperties,
+    });
+  });
+
+  it('accepts spacing based on breakpoints', () => {
+    const stack = mountWithApp(
+      <AlphaStack spacing={{xs: '2', md: '8'}}>{children}</AlphaStack>,
+    );
+
+    expect(stack).toContainReactComponent('div', {
+      style: expect.objectContaining({
+        '--pc-stack-spacing-md': 'var(--p-space-8)',
+        '--pc-stack-spacing-xs': 'var(--p-space-2)',
+      }) as React.CSSProperties,
     });
   });
 });

polaris-react/src/utilities/css.ts

@@ -1,5 +1,13 @@
+import type {BreakpointsAlias} from '@shopify/polaris-tokens';
+
 type Falsy = boolean | undefined | null | 0;
 
+export type ResponsiveProp<T> =
+  | T
+  | {
+      [Breakpoint in BreakpointsAlias]?: T;
+    };
+
 export function classNames(...classes: (string | Falsy)[]) {
   return classes.filter(Boolean).join(' ');
 }
@@ -17,3 +25,27 @@ export function sanitizeCustomProperties(
 
   return nonNullValues.length ? Object.fromEntries(nonNullValues) : undefined;
 }
+
+export function getResponsiveProps(
+  componentName: string,
+  componentProp: string,
+  tokenSubgroup: string,
+  responsiveProp:
+    | string
+    | {
+        [Breakpoint in BreakpointsAlias]?: string;
+      },
+) {
+  if (typeof responsiveProp === 'string') {
+    return {
+      [`--pc-${componentName}-${componentProp}-xs`]: `var(--p-${tokenSubgroup}-${responsiveProp})`,
+    };
+  }
+
+  return Object.fromEntries(
+    Object.entries(responsiveProp).map(([breakpointAlias, aliasOrScale]) => [
+      `--pc-${componentName}-${componentProp}-${breakpointAlias}`,
+      `var(--p-${tokenSubgroup}-${aliasOrScale})`,
+    ]),
+  );
+}

polaris-react/src/utilities/tests/css.test.ts

@@ -1,4 +1,4 @@
-import {classNames, variationName} from '../css';
+import {classNames, variationName, getResponsiveProps} from '../css';
 
 describe('classNames', () => {
   it('returns a single string from multiple classes', () => {
@@ -24,3 +24,20 @@ describe('variationName', () => {
     expect(variationName('size', 'medium')).toBe('sizeMedium');
   });
 });
+
+describe('getResponsiveProps', () => {
+  it('takes a string and returns the custom property', () => {
+    expect(getResponsiveProps('stack', 'space', 'space', '4')).toMatchObject({
+      '--pc-stack-space-xs': 'var(--p-space-4)',
+    });
+  });
+
+  it('takes an object with a breakpoint and value and returns the property for each breakpoint', () => {
+    expect(
+      getResponsiveProps('stack', 'space', 'space', {xs: '2', md: '8'}),
+    ).toMatchObject({
+      '--pc-stack-space-xs': 'var(--p-space-2)',
+      '--pc-stack-space-md': 'var(--p-space-8)',
+    });
+  });
+});