Extend Grid layout with custom rows and columns options and more (#149)

.eslintrc

@@ -25,7 +25,8 @@
       "rules": {
         "react/jsx-filename-extension": [1, { "extensions": [".mdx"] }],
         "react/jsx-indent": "off", // Gives false positives in MDX files.
-        "semi": "off" // We don't want to clutter our MDX with semicolons.
+        "semi": "off", // We don't want to clutter our MDX with semicolons.
+        "sort-keys": "off" // This rule only needs to be turned off in a few places (eg. breakpoint lists), but weirdly enough, an inline comment alerts breaking of the `indent` rule.
       }
     }
   ]

src/gatsby-theme-docz/wrapper.js

@@ -23,6 +23,15 @@ const Wrapper = ({ children }) => (
           gtag('config', 'UA-173070814-1');
         `}
       </script>
+      <style type="text/css">
+        {`
+          @media (prefers-reduced-motion: no-preference) {
+            html {
+              scroll-behavior: smooth;
+            }
+          }
+        `}
+      </style>
     </Helmet>
     {children}
   </>

src/lib/components/layout/CTA/README.mdx

@@ -100,19 +100,19 @@ and bottom.
 
 <Props of={CTA} />
 
-## CTAStart
+### CTAStart
 
 The start element of the CTA layout.
 
 <Props of={CTAStart} />
 
-## CTACenter
+### CTACenter
 
 The center element of the CTA layout.
 
 <Props of={CTACenter} />
 
-## CTAEnd
+### CTAEnd
 
 The end element of the CTA layout.
 

src/lib/components/layout/FormLayout/FormLayout.jsx

@@ -55,6 +55,10 @@ export const FormLayout = (props) => {
       ].join(' ')}
       {...hasCustomLabelWidth ? { style: { '--rui-custom-label-width': labelWidth } } : {}}
     >
+      {/*
+        Flatten children to one-dimensional array so we get over React Fragments with the `map()`
+        function.
+      */}
       {flattenChildren(children).map((child) => {
         if (!React.isValidElement(child)) {
           return null;

src/lib/components/layout/FormLayout/README.mdx

@@ -367,7 +367,7 @@ This is a demo of all components supported by FormLayout.
 
 <Props of={FormLayout} />
 
-## FormLayoutCustomField
+### FormLayoutCustomField
 
 A place for custom content inside FormLayout.
 

src/lib/components/layout/Grid/Grid.jsx

@@ -1,50 +1,131 @@
-import flattenChildren from 'react-keyed-flatten-children';
 import PropTypes from 'prop-types';
 import React from 'react';
+import { generateResponsiveCustomProperties } from './helpers/generateResponsiveCustomProperties';
 import styles from './Grid.scss';
 
-export const Grid = (props) => {
-  const {
-    children,
-    id,
-    ...other
-  } = props;
-
-  if (!props.children) {
+export const Grid = ({
+  autoFlow,
+  children,
+  columnGap,
+  columns,
+  id,
+  rowGap,
+  rows,
+  ...other
+}) => {
+  if (!children) {
     return null;
   }
 
   return (
     <div
       id={id}
       className={styles.root}
+      style={{
+        '--rui-local-auto-flow': autoFlow,
+        ...generateResponsiveCustomProperties(columns, 'columns'),
+        ...generateResponsiveCustomProperties(columnGap, 'column-gap'),
+        ...generateResponsiveCustomProperties(rows, 'rows'),
+        ...generateResponsiveCustomProperties(rowGap, 'row-gap'),
+      }}
       {...other}
     >
-      {flattenChildren(children).map((child) => {
-        if (!React.isValidElement(child)) {
-          return null;
-        }
-
-        return React.cloneElement(child);
-      })}
+      {children}
     </div>
   );
 };
 
+/* Breakpoints are easier to work with when ordered according to their value, not name. */
+/* eslint-disable sort-keys */
+
 Grid.defaultProps = {
   children: null,
+  columnGap: undefined,
+  columns: undefined,
+  autoFlow: undefined,
   id: undefined,
+  rowGap: undefined,
+  rows: undefined,
 };
 
 Grid.propTypes = {
+  /**
+   * Grid auto-flow algorithm to be used. Accepts any valid value of `grid-auto-flow` CSS property.
+   * See [MDN](https://developer.mozilla.org/en-US/docs/Web/CSS/grid-auto-flow) for more.
+   */
+  autoFlow: PropTypes.oneOf(['row', 'column', 'dense', 'row dense', 'column dense']),
   /**
    * Items to be aligned in the grid.
    */
   children: PropTypes.node,
+  /**
+   * Gap between columns. Accepts any valid value of `grid-column-gap` CSS property.
+   * See [MDN](https://developer.mozilla.org/en-US/docs/Web/CSS/column-gap) for more.
+   */
+  columnGap: PropTypes.oneOf([
+    PropTypes.string,
+    PropTypes.shape({
+      xs: PropTypes.string,
+      sm: PropTypes.string,
+      md: PropTypes.string,
+      lg: PropTypes.string,
+      xl: PropTypes.string,
+      xxl: PropTypes.string,
+      xxxl: PropTypes.string,
+    }),
+  ]),
+  /**
+   * Grid columns. Accepts any valid value of `grid-template-columns` CSS property.
+   * See [MDN](https://developer.mozilla.org/en-US/docs/Web/CSS/grid-template-columns) for more.
+   */
+  columns: PropTypes.oneOf([
+    PropTypes.string,
+    PropTypes.shape({
+      xs: PropTypes.string,
+      sm: PropTypes.string,
+      md: PropTypes.string,
+      lg: PropTypes.string,
+      xl: PropTypes.string,
+      xxl: PropTypes.string,
+      xxxl: PropTypes.string,
+    }),
+  ]),
   /**
    * ID of the root HTML element.
    */
   id: PropTypes.string,
+  /**
+   * Gap between rows. Accepts any valid value of `grid-row-gap` CSS property.
+   * See [MDN](https://developer.mozilla.org/en-US/docs/Web/CSS/row-gap) for more.
+   */
+  rowGap: PropTypes.oneOf([
+    PropTypes.string,
+    PropTypes.shape({
+      xs: PropTypes.string,
+      sm: PropTypes.string,
+      md: PropTypes.string,
+      lg: PropTypes.string,
+      xl: PropTypes.string,
+      xxl: PropTypes.string,
+      xxxl: PropTypes.string,
+    }),
+  ]),
+  /**
+   * Grid rows. Accepts any valid value of `grid-template-rows` CSS property.
+   * See [MDN](https://developer.mozilla.org/en-US/docs/Web/CSS/grid-template-rows) for more.
+   */
+  rows: PropTypes.oneOf([
+    PropTypes.string,
+    PropTypes.shape({
+      xs: PropTypes.string,
+      sm: PropTypes.string,
+      md: PropTypes.string,
+      lg: PropTypes.string,
+      xl: PropTypes.string,
+      xxl: PropTypes.string,
+      xxxl: PropTypes.string,
+    }),
+  ]),
 };
 
 export default Grid;

src/lib/components/layout/Grid/Grid.scss

@@ -1,17 +1,56 @@
+// 1. Read value of `--rui-local-<PROPERTY>-<BREAKPOINT>` that might have been defined by
+//    JavaScript and assign it to `--rui-local-<PROPERTY>` used in 2.
+//
+//    Fallback cascade containing fallbacks for all previous breakpoints recursively is included
+//    using CSS custom property fallback mechanism like this:
+//
+//    Fallback for `xs` breakpoint: `<INITIAL FALLBACK>`
+//    Fallback for `sm` breakpoint: `var(--rui-local-<PROPERTY>-xs, <INITIAL FALLBACK>)`
+//    Fallback for `md` breakpoint: `var(--rui-local-<PROPERTY>-sm, var(--rui-local-<PROPERTY>-xs, <INITIAL FALLBACK>))`
+//
+//    … etc, up to the largest breakpoint.
+//
+//    A media query is then created for each breakpoint (with exception of `xs` which doesn't need a
+//    media query) and a corresponding responsive custom property variant is assigned to
+//    `--rui-local-<PROPERTY>` that is used later in CSS, see 2.
+//
+//    Example for `sm` breakpoint:
+//
+//    `--rui-local-<PROPERTY>: var(--rui-local-<PROPERTY>-sm, var(--rui-local-<PROPERTY>-xs, <INITIAL FALLBACK>))`
+//
+// 2. Apply custom property value that is defined within current breakpoint, see 1.
+//
+// 3. Any valid auto-flow algorithm can be used. It's applied globally for all breakpoints.
+
 @import '../../../styles/settings/layouts';
-@import '../../../styles/tools/breakpoints';
-@import './theme';
+@import 'mixins';
 
-/* autoprefixer grid: off */
 .root {
+  $_properties: (
+    columns: var(--rui-grid-columns),
+    column-gap: var(--rui-grid-column-gap),
+    rows: var(--rui-grid-rows),
+    row-gap: var(--rui-grid-row-gap),
+  );
+
+  @include assign-responsive-custom-properties($_properties); // 1.
+
   display: grid;
-  grid-template-columns: 1fr;
-  grid-template-rows: auto;
-  grid-gap: $grid-gap;
+  grid-template-columns: var(--rui-local-columns); // 2.
+  grid-template-rows: var(--rui-local-rows); // 2.
+  grid-gap: var(--rui-local-row-gap) var(--rui-local-column-gap); // 2.
+  grid-auto-flow: var(--rui-local-auto-flow, var(--rui-grid-auto-flow)); // 3.
   margin-bottom: $layout-common-bottom-spacing;
+}
+
+.span {
+  $_properties: (
+    column-span: 1,
+    row-span: 1,
+  );
+
+  @include assign-responsive-custom-properties($_properties); // 1.
 
-  @include breakpoint-up(sm) {
-    grid-template-columns: repeat(auto-fit, minmax($grid-item-min-width, $grid-item-max-width));
-    justify-content: start;
-  }
+  grid-column: span var(--rui-local-column-span, 1); // 2.
+  grid-row: span var(--rui-local-row-span, 1); // 2.
 }