feat: add Stack component (react-bootstrap#5987)

Author: kyletsang

src/Stack.tsx

@@ -0,0 +1,69 @@
+import classNames from 'classnames';
+import * as React from 'react';
+import PropTypes from 'prop-types';
+import { useBootstrapPrefix } from './ThemeProvider';
+import { BsPrefixProps, BsPrefixRefForwardingComponent } from './helpers';
+import { GapValue } from './types';
+import createUtilityClassName, {
+  ResponsiveUtilityValue,
+  responsivePropType,
+} from './createUtilityClasses';
+
+export type StackDirection = 'horizontal' | 'vertical';
+
+export interface StackProps
+  extends BsPrefixProps,
+    React.HTMLAttributes<HTMLElement> {
+  direction?: StackDirection;
+  gap?: ResponsiveUtilityValue<GapValue>;
+}
+
+const propTypes = {
+  /**
+   * Change the underlying component CSS base class name and modifier class names prefix.
+   * **This is an escape hatch** for working with heavily customized bootstrap css.
+   *
+   * Defaults to `hstack` if direction is `horizontal` or `vstack` if direction
+   * is `vertical`.
+   *
+   * @default 'hstack | vstack'
+   */
+  bsPrefix: PropTypes.string,
+
+  /**
+   * Sets the spacing between each item. Valid values are `0-5`.
+   */
+  gap: responsivePropType(PropTypes.number),
+};
+
+const Stack: BsPrefixRefForwardingComponent<'span', StackProps> =
+  React.forwardRef<HTMLElement, StackProps>(
+    (
+      { as: Component = 'div', bsPrefix, className, direction, gap, ...props },
+      ref,
+    ) => {
+      bsPrefix = useBootstrapPrefix(
+        bsPrefix,
+        direction === 'horizontal' ? 'hstack' : 'vstack',
+      );
+
+      return (
+        <Component
+          {...props}
+          ref={ref}
+          className={classNames(
+            className,
+            bsPrefix,
+            ...createUtilityClassName({
+              gap,
+            }),
+          )}
+        />
+      );
+    },
+  );
+
+Stack.displayName = 'Stack';
+Stack.propTypes = propTypes;
+
+export default Stack;

src/createUtilityClasses.ts

@@ -0,0 +1,51 @@
+import PropTypes from 'prop-types';
+
+export type ResponsiveUtilityValue<T> =
+  | T
+  | {
+      xs?: T;
+      sm?: T;
+      md?: T;
+      lg?: T;
+      xl?: T;
+      xxl?: T;
+    };
+
+export function responsivePropType(propType: any) {
+  return PropTypes.oneOfType([
+    propType,
+    PropTypes.shape({
+      xs: propType,
+      sm: propType,
+      md: propType,
+      lg: propType,
+      xl: propType,
+      xxl: propType,
+    }),
+  ]);
+}
+
+export const DEVICE_SIZES = ['xxl', 'xl', 'lg', 'md', 'sm', 'xs'] as const;
+
+export default function createUtilityClassName(
+  utilityValues: Record<string, ResponsiveUtilityValue<unknown>>,
+) {
+  const classes: string[] = [];
+  Object.entries(utilityValues).forEach(([utilName, utilValue]) => {
+    if (utilValue != null) {
+      if (typeof utilValue === 'object') {
+        DEVICE_SIZES.forEach((brkPoint) => {
+          const bpValue = utilValue![brkPoint];
+          if (bpValue != null) {
+            const infix = brkPoint !== 'xs' ? `-${brkPoint}` : '';
+            classes.push(`${utilName}${infix}-${bpValue}`);
+          }
+        });
+      } else {
+        classes.push(`${utilName}-${utilValue}`);
+      }
+    }
+  });
+
+  return classes;
+}

src/index.tsx

@@ -181,6 +181,9 @@ export type { SplitButtonProps } from './SplitButton';
 export { default as SSRProvider } from './SSRProvider';
 export type { SSRProviderProps } from './SSRProvider';
 
+export { default as Stack } from './Stack';
+export type { StackProps } from './Stack';
+
 export { default as Tab } from './Tab';
 export type { TabProps } from './Tab';
 

src/types.tsx

@@ -58,3 +58,5 @@ export const alignPropType = PropTypes.oneOfType([
 ]);
 
 export type RootCloseEvent = 'click' | 'mousedown';
+
+export type GapValue = 0 | 1 | 2 | 3 | 4 | 5;

test/StackSpec.tsx

@@ -0,0 +1,25 @@
+import { render } from '@testing-library/react';
+
+import Stack from '../src/Stack';
+
+describe('<Stack>', () => {
+  it('should render a vertical stack by default', () => {
+    const { container } = render(<Stack />);
+    container.firstElementChild!.className.should.contain('vstack');
+  });
+
+  it('should render direction', () => {
+    const { container } = render(<Stack direction="horizontal" />);
+    container.firstElementChild!.className.should.contain('hstack');
+  });
+
+  it('should render gap', () => {
+    const { container } = render(<Stack gap={2} />);
+    container.firstElementChild!.classList.contains('gap-2').should.be.true;
+  });
+
+  it('should render responsive gap', () => {
+    const { container } = render(<Stack gap={{ md: 2 }} />);
+    container.firstElementChild!.classList.contains('gap-md-2').should.be.true;
+  });
+});

test/createUtilityClassesSpec.ts

@@ -0,0 +1,64 @@
+import createUtilityClasses from '../src/createUtilityClasses';
+
+describe('createUtilityClassName', () => {
+  it('should not create a class when value is not defined', () => {
+    const classList = createUtilityClasses({
+      gap: undefined,
+    });
+
+    classList.length.should.equal(0);
+  });
+
+  it('should handle falsy values', () => {
+    const classList = createUtilityClasses({
+      gap: 0,
+    });
+
+    classList.length.should.equal(1);
+    classList.should.include.all.members(['gap-0']);
+  });
+
+  it('should handle responsive falsy values', () => {
+    const classList = createUtilityClasses({
+      gap: { xs: 0, md: 0 },
+    });
+
+    classList.length.should.equal(2);
+    classList.should.include.all.members(['gap-0', 'gap-md-0']);
+  });
+
+  it('should return `utilityName-value` when value is a primitive', () => {
+    const classList = createUtilityClasses({
+      gap: 2,
+    });
+
+    classList.length.should.equal(1);
+    classList.should.include.all.members(['gap-2']);
+  });
+
+  it('should return responsive class when value is a responsive type', () => {
+    const classList = createUtilityClasses({
+      gap: { xs: 2, lg: 3, xxl: 4 },
+    });
+
+    classList.length.should.equal(3);
+    classList.should.include.all.members(['gap-2', 'gap-lg-3', 'gap-xxl-4']);
+  });
+
+  it('should return multiple classes', () => {
+    const classList = createUtilityClasses({
+      gap: { xs: 2, lg: 3, xxl: 4 },
+      text: { xs: 'start', md: 'end', xl: 'start' },
+    });
+
+    classList.length.should.equal(6);
+    classList.should.include.all.members([
+      'gap-2',
+      'gap-lg-3',
+      'gap-xxl-4',
+      'text-start',
+      'text-md-end',
+      'text-xl-start',
+    ]);
+  });
+});

tests/simple-types-test.tsx

@@ -39,6 +39,7 @@ import {
   ProgressBar,
   Spinner,
   SplitButton,
+  Stack,
   Table,
   Tabs,
   Tab,
@@ -1011,6 +1012,11 @@ const MegaComponent = () => (
       <ToggleButton value={2}>Radio 2</ToggleButton>
       <ToggleButton value={3}>Radio 3</ToggleButton>
     </ToggleButtonGroup>
+    <Stack direction="horizontal" gap={1} />
+    <Stack
+      direction="vertical"
+      gap={{ xs: 2, sm: 2, md: 2, lg: 2, xl: 2, xxl: 2 }}
+    />
     {/* // As = ComponentClass // TODO: Reinstate these? What _is_ ExpectError? */}
     {/*
     <Tabs invalidProp="2" />; // $ExpectError

www/src/components/SideNav.js

@@ -108,7 +108,7 @@ const gettingStarted = [
   'server-side-rendering',
 ];
 
-const layout = ['grid'];
+const layout = ['grid', 'stack'];
 
 const components = [
   'alerts',

www/src/examples/Stack/Buttons.js

@@ -0,0 +1,4 @@
+<Stack gap={2} className="col-md-5 mx-auto">
+  <Button variant="secondary">Save changes</Button>
+  <Button variant="outline-secondary">Cancel</Button>
+</Stack>;

www/src/examples/Stack/Form.js

@@ -0,0 +1,6 @@
+<Stack direction="horizontal" gap={3}>
+  <Form.Control className="me-auto" placeholder="Add your item here..." />
+  <Button variant="secondary">Submit</Button>
+  <div className="vr" />
+  <Button variant="outline-danger">Reset</Button>
+</Stack>;

www/src/examples/Stack/Horizontal.js

@@ -0,0 +1,5 @@
+<Stack direction="horizontal" gap={3}>
+  <div className="bg-light border">First item</div>
+  <div className="bg-light border">Second item</div>
+  <div className="bg-light border">Third item</div>
+</Stack>;

www/src/examples/Stack/HorizontalMarginStart.js

@@ -0,0 +1,5 @@
+<Stack direction="horizontal" gap={3}>
+  <div className="bg-light border">First item</div>
+  <div className="bg-light border ms-auto">Second item</div>
+  <div className="bg-light border">Third item</div>
+</Stack>;

www/src/examples/Stack/HorizontalVerticalRules.js

@@ -0,0 +1,6 @@
+<Stack direction="horizontal" gap={3}>
+  <div className="bg-light border">First item</div>
+  <div className="bg-light border ms-auto">Second item</div>
+  <div className="vr" />
+  <div className="bg-light border">Third item</div>
+</Stack>;

www/src/examples/Stack/Vertical.js

@@ -0,0 +1,5 @@
+<Stack gap={3}>
+  <div className="bg-light border">First item</div>
+  <div className="bg-light border">Second item</div>
+  <div className="bg-light border">Third item</div>
+</Stack>;

www/src/pages/layout/stack.mdx

@@ -0,0 +1,65 @@
+import { graphql } from 'gatsby';
+
+import Callout from '../../components/Callout';
+import ComponentApi from '../../components/ComponentApi';
+import ReactPlayground from '../../components/ReactPlayground';
+
+import StackButtons from '../../examples/Stack/Buttons'
+import StackForm from '../../examples/Stack/Form'
+import StackHorizontal from '../../examples/Stack/Horizontal';
+import StackHorizontalMarginStart from '../../examples/Stack/HorizontalMarginStart';
+import StackHorizontalVerticalRules from '../../examples/Stack/HorizontalVerticalRules';
+import StackVertical from '../../examples/Stack/Vertical';
+
+# Stacks
+
+<p className="lead">
+  Shorthand helpers that build on top of our flexbox utilities to make component
+  layout faster and easier than ever.
+</p>
+
+## Vertical
+
+Stacks are vertical by default and stacked items are full-width by default. Use the `gap`
+prop to add space between items.
+
+<ReactPlayground codeText={StackVertical} />
+
+## Horizontal
+
+Use `direction="horizontal"` for horizontal layouts. Stacked items are vertically centered
+by default and only take up their necessary width. Use the `gap` prop to add space between
+items.
+
+<ReactPlayground codeText={StackHorizontal} />
+
+Using horizontal margin utilities like `.ms-auto` as spacers:
+
+<ReactPlayground codeText={StackHorizontalMarginStart} />
+
+And with vertical rules:
+
+<ReactPlayground codeText={StackHorizontalVerticalRules} />
+
+## Examples
+
+Use a vertical `Stack` to stack buttons and other elements:
+
+<ReactPlayground codeText={StackButtons} />
+
+Create an inline form with a horizontal `Stack`:
+
+<ReactPlayground codeText={StackForm} />
+
+## API
+
+<ComponentApi metadata={props.data.Stack} />
+
+export const query = graphql`
+  query Stack {
+    Stack: componentMetadata(displayName: { eq: "Stack" }) {
+      displayName
+      ...ComponentApi_metadata
+    }
+  }
+`;