[AlphaStack] Add withDivider prop to insert Dividers between stack children

.changeset/cold-dingos-knock.md

@@ -0,0 +1,5 @@
+---
+'@shopify/polaris': minor
+---
+
+<AlphaStack> now accepts `withDivider` prop to automatically insert <Divider /> between stack children (with optional style).

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

@@ -101,3 +101,35 @@ export function WithAlignEnd() {
     </AlphaStack>
   );
 }
+
+export function WithDivider() {
+  return (
+    <AlphaStack gap="4" withDivider>
+      <Box background="surface" padding="1">
+        01
+      </Box>
+      <Box background="surface" padding="1">
+        02
+      </Box>
+      <Box background="surface" padding="1">
+        03
+      </Box>
+    </AlphaStack>
+  );
+}
+
+export function WithStyledDivider() {
+  return (
+    <AlphaStack gap="4" withDivider="dark">
+      <Box background="surface" padding="1">
+        01
+      </Box>
+      <Box background="surface" padding="1">
+        02
+      </Box>
+      <Box background="surface" padding="1">
+        03
+      </Box>
+    </AlphaStack>
+  );
+}

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

@@ -1,6 +1,7 @@
-import React, {createElement} from 'react';
+import React, {Fragment, createElement} from 'react';
 import type {SpacingSpaceScale} from '@shopify/polaris-tokens';
 
+import {Divider, type DividerProps} from '../Divider';
 import {
   classNames,
   sanitizeCustomProperties,
@@ -32,6 +33,11 @@ export interface AlphaStackProps extends React.AriaAttributes {
    * @default false
    */
   reverseOrder?: boolean;
+  /** Render a <Divider /> between each stack child. Setting to `true` will
+   * render the default style of <Divider />
+   * @default false
+   */
+  withDivider?: boolean | DividerProps['borderStyle'];
 }
 
 export const AlphaStack = ({
@@ -41,6 +47,7 @@ export const AlphaStack = ({
   gap,
   id,
   reverseOrder = false,
+  withDivider = false,
   ...restProps
 }: AlphaStackProps) => {
   const className = classNames(
@@ -55,13 +62,32 @@ export const AlphaStack = ({
     ...getResponsiveProps('stack', 'gap', 'space', gap),
   } as React.CSSProperties;
 
+  let dividedChildren = children;
+
+  if (withDivider) {
+    const dividerProps =
+      typeof withDivider === 'boolean' ? {} : {borderStyle: withDivider};
+
+    dividedChildren = React.Children.map(children, (child, index) => {
+      if (index === 0) {
+        return child;
+      }
+      return (
+        <Fragment key={index}>
+          <Divider {...dividerProps} />
+          {child}
+        </Fragment>
+      );
+    });
+  }
+
   return createElement(
     as,
     {
       className,
       style: sanitizeCustomProperties(style),
       ...restProps,
     },
-    children,
+    dividedChildren,
   );
 };

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

@@ -2,9 +2,10 @@ import React from 'react';
 import {mountWithApp} from 'tests/utilities';
 
 import {AlphaStack} from '../AlphaStack';
+import {Divider} from '../../Divider';
 
 const text = 'This is a stack';
-const children = <p>{text}</p>;
+const children = [<p key="1">{text}</p>, <p key="2">{text}</p>];
 
 describe('<AlphaStack />', () => {
   it('renders children', () => {
@@ -50,4 +51,20 @@ describe('<AlphaStack />', () => {
       }) as React.CSSProperties,
     });
   });
+
+  it('renders n-1 dividers', () => {
+    const stack = mountWithApp(<AlphaStack withDivider>{children}</AlphaStack>);
+
+    expect(stack).toContainReactComponentTimes(Divider, children.length - 1);
+  });
+
+  it('renders dividers with given style', () => {
+    const stack = mountWithApp(
+      <AlphaStack withDivider="dark">{children}</AlphaStack>,
+    );
+
+    expect(stack).toContainReactComponentTimes(Divider, children.length - 1, {
+      borderStyle: 'dark',
+    });
+  });
 });

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

@@ -23,6 +23,11 @@ examples:
     title: Align
     description: >-
       Control the horizontal alignment of children using the `align` prop.
+  - fileName: alpha-stack-with-divider.tsx
+    title: With divider
+    description: >-
+      Automatically insert a `<Divider />` between children using the
+      `withDivider` prop.
 ---
 
 ## Best practices

polaris.shopify.com/pages/examples/alpha-stack-with-divider.tsx

@@ -0,0 +1,15 @@
+import React from 'react';
+import {AlphaStack, Box} from '@shopify/polaris';
+
+import {withPolarisExample} from '../../src/components/PolarisExampleWrapper';
+function AlphaStackWithDividerExample() {
+  return (
+    <AlphaStack gap="4" withDivider="divider">
+      <Box background="surface-success">&nbsp;</Box>
+      <Box background="surface-success">&nbsp;</Box>
+      <Box background="surface-success">&nbsp;</Box>
+    </AlphaStack>
+  );
+}
+
+export default withPolarisExample(AlphaStackWithDividerExample);