feat(Stack): add Item to adjust single child

docs/pages/components/stack/en-US/index.md

@@ -28,6 +28,10 @@ Quickly layout components through Flexbox, support vertical and horizontal stack
 
  <!--{include:`interactive.md`}-->
 
+### Adjust Single Item
+
+ <!--{include:`adjust-single-item.md`}-->
+
 ## Props
 
 ### `<Stack>`
@@ -41,3 +45,14 @@ Quickly layout components through Flexbox, support vertical and horizontal stack
 | justifyContent | 'flex-start' &#124; 'center' &#124; 'flex-end' &#124; 'space-between' &#124; 'space-around' | Define the alignment of the children in the stack on the inline axis                              |
 | spacing        | number &#124; string                                                                        | Define the spacing between immediate children                                                     |
 | wrap           | boolean                                                                                     | Define whether the children in the stack are forced onto one line or can wrap onto multiple lines |
+
+### `<Stack.Item>`
+
+| Property  | Type`(default)`                                                                   | Description                                                                          |
+| --------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
+| alignSelf | 'flex-start' &#124; 'center' &#124; 'flex-end' &#124; 'stretch' &#124; 'baseline' | Define the alignment of the Item in the stack                                        |
+| flex      | string &#124; number                                                              | Define the item will grow or shrink to fit the space available in its flex container |
+| grow      | string &#124; number                                                              | Define the item grow factor of a flex item main size                                 |
+| shrink    | number                                                                            | Define the item shrink factor of a flex item                                         |
+| basis     | string                                                                            | Define the initial main size of the item                                             |
+| order     | number                                                                            | Define the order of the item in the stack                                            |

docs/pages/components/stack/fragments/adjust-single-item.md

@@ -0,0 +1,27 @@
+<!--start-code-->
+
+```js
+import { Stack, Button } from 'rsuite';
+
+const App = () => {
+  return (
+    <Stack alignItems="flex-start" spacing={10}>
+      <Button size="lg">Item 1</Button>
+      <Button size="md">Item 2</Button>
+      <Button size="sm">Item 3</Button>
+      <Stack.Item alignSelf="flex-end">
+        <Button size="xs">Item 4</Button>
+      </Stack.Item>
+      <Stack.Item grow={1}>
+        <Button size="md" block>
+          Item 5
+        </Button>
+      </Stack.Item>
+    </Stack>
+  );
+};
+
+ReactDOM.render(<App />, document.getElementById('root'));
+```
+
+<!--end-code-->

src/Stack/Stack.tsx

@@ -1,7 +1,8 @@
 import React from 'react';
 import PropTypes from 'prop-types';
 import { useClassNames, useCustom, isSupportFlexGap } from '../utils';
-import { WithAsProps } from '../@types/common';
+import { RsRefForwardingComponent, WithAsProps } from '../@types/common';
+import StackItem from './StackItem';
 
 export interface StackProps extends WithAsProps {
   /**
@@ -31,6 +32,10 @@ export interface StackProps extends WithAsProps {
   wrap?: boolean;
 }
 
+export interface StackComponent extends RsRefForwardingComponent<'div', StackProps> {
+  Item: typeof StackItem;
+}
+
 const Stack = React.forwardRef((props: StackProps, ref: React.Ref<HTMLDivElement>) => {
   const {
     as: Component = 'div',
@@ -71,17 +76,33 @@ const Stack = React.forwardRef((props: StackProps, ref: React.Ref<HTMLDivElement
   return (
     <Component {...rest} ref={ref} className={classes} style={styles}>
       {React.Children.map(children as React.ReactElement[], (child, index) => {
-        const childNode = (
-          <div className={prefix('item')} style={!isSupportGridGap ? itemStyles : undefined}>
-            {child}
-          </div>
-        );
+        const childNode =
+          child.type !== StackItem ? (
+            <StackItem
+              className={prefix('item')}
+              style={!isSupportGridGap ? itemStyles : undefined}
+            >
+              {child}
+            </StackItem>
+          ) : (
+            React.cloneElement(child, {
+              className: merge(prefix('item'), child.props.className),
+              style: !isSupportGridGap
+                ? {
+                    ...itemStyles,
+                    ...child.props.style
+                  }
+                : child.props.style
+            })
+          );
 
         return [childNode, index < count - 1 ? divider : null];
       })}
     </Component>
   );
-});
+}) as unknown as StackComponent;
+
+Stack.Item = StackItem;
 
 Stack.displayName = 'Stack';
 Stack.propTypes = {

src/Stack/StackItem.tsx

@@ -0,0 +1,52 @@
+import React from 'react';
+import PropTypes from 'prop-types';
+import { WithAsProps } from '../@types/common';
+
+export interface StackItemProps extends WithAsProps {
+  alignSelf?: 'flex-start' | 'flex-end' | 'center' | 'baseline' | 'stretch';
+  flex?: React.CSSProperties['flex'];
+  grow?: React.CSSProperties['flexGrow'];
+  shrink?: React.CSSProperties['flexShrink'];
+  basis?: React.CSSProperties['flexBasis'];
+  order?: React.CSSProperties['order'];
+}
+
+export default function StackItem(props: StackItemProps) {
+  const {
+    as: Component = 'div',
+    style,
+    className,
+    alignSelf,
+    flex,
+    grow,
+    shrink,
+    order,
+    basis,
+    ...rest
+  } = props;
+
+  return (
+    <Component
+      className={className}
+      style={{
+        alignSelf,
+        order,
+        ...(flex ? { flex } : { flexGrow: grow, flexShrink: shrink, flexBasis: basis }),
+        ...style
+      }}
+      {...rest}
+    />
+  );
+}
+
+StackItem.displayName = 'StackItem';
+StackItem.propTypes = {
+  className: PropTypes.string,
+  children: PropTypes.node,
+  alignSelf: PropTypes.oneOf(['flex-start', 'flex-end', 'center', 'baseline', 'stretch']),
+  flex: PropTypes.oneOfType([PropTypes.string, PropTypes.number]),
+  grow: PropTypes.number,
+  shrink: PropTypes.number,
+  order: PropTypes.number,
+  basis: PropTypes.string
+};

src/Stack/test/StackItemSpec.js

@@ -0,0 +1,56 @@
+import React from 'react';
+import { render } from '@testing-library/react';
+import Stack from '../Stack';
+import StackItem from '../StackItem';
+import Button from '../../Button';
+
+describe('StackItem', () => {
+  it('renders a StackItem', () => {
+    const screen = render(
+      <Stack>
+        <StackItem>stack item</StackItem>
+      </Stack>
+    );
+    expect(screen.getByText('stack item').className).to.include('rs-stack-item');
+    expect(screen.getByText('stack item').parentNode.className).to.equal('rs-stack');
+  });
+
+  it('renders a StackItem with flex props', () => {
+    const screen = render(
+      <Stack>
+        <StackItem flex="auto" grow={2} alignSelf="flex-end" order={1}>
+          stack item
+        </StackItem>
+      </Stack>
+    );
+    expect(screen.getByText('stack item').style.flex).to.equal('1 1 auto');
+    /**
+     * inline css shorthand property will override longhand properties
+     */
+    expect(screen.getByText('stack item').style.flexGrow).to.equal('1');
+    expect(screen.getByText('stack item').style.alignSelf).to.equal('flex-end');
+    expect(screen.getByText('stack item').style.order).to.equal('1');
+  });
+
+  it('should render a stackitem with custom class name', () => {
+    const screen = render(
+      <Stack>
+        <StackItem className="custom">custom element</StackItem>
+      </Stack>
+    );
+
+    expect(screen.getByText('custom element').className).to.include('custom');
+    expect(screen.getByText('custom element').className).to.include('rs-stack-item');
+  });
+
+  it('should render a stackitem as Button', () => {
+    const screen = render(
+      <Stack>
+        <StackItem as={Button}>custom element</StackItem>
+      </Stack>
+    );
+
+    expect(screen.getByText('custom element').className).to.include('rs-btn');
+    expect(screen.getByText('custom element').className).to.include('rs-stack-item');
+  });
+});