@react-ui-org/react-ui 0.47.0 → 0.49.0

package/src/lib/components/Grid/Grid.jsx

@@ -2,9 +2,12 @@ import PropTypes from 'prop-types';
 import React from 'react';
 import { withGlobalProps } from '../../provider';
 import { isChildrenEmpty } from '../_helpers/isChildrenEmpty';
+import { transferProps } from '../_helpers/transferProps';
 import { generateResponsiveCustomProperties } from './_helpers/generateResponsiveCustomProperties';
 import styles from './Grid.scss';
 
+const SPACING_VALUES = [0, 1, 2, 3, 4, 5, 6, 7];
+
 export const Grid = ({
   alignContent,
   alignItems,
@@ -12,13 +15,12 @@ export const Grid = ({
   children,
   columnGap,
   columns,
-  id,
   justifyContent,
   justifyItems,
   rowGap,
   rows,
   tag: Tag,
-  ...other
+  ...restProps
 }) => {
   if (isChildrenEmpty(children)) {
     return null;
@@ -26,20 +28,19 @@ export const Grid = ({
 
   return (
     <Tag
-      id={id}
+      {...transferProps(restProps)}
       className={styles.root}
       style={{
         ...generateResponsiveCustomProperties(columns, 'columns'),
-        ...generateResponsiveCustomProperties(columnGap, 'column-gap'),
+        ...generateResponsiveCustomProperties(columnGap, 'column-gap', 'spacing'),
         ...generateResponsiveCustomProperties(rows, 'rows'),
-        ...generateResponsiveCustomProperties(rowGap, 'row-gap'),
+        ...generateResponsiveCustomProperties(rowGap, 'row-gap', 'spacing'),
         ...generateResponsiveCustomProperties(autoFlow, 'auto-flow'),
         ...generateResponsiveCustomProperties(alignContent, 'align-content'),
         ...generateResponsiveCustomProperties(alignItems, 'align-items'),
         ...generateResponsiveCustomProperties(justifyContent, 'justify-content'),
         ...generateResponsiveCustomProperties(justifyItems, 'justify-items'),
       }}
-      {...other}
     >
       {children}
     </Tag>
@@ -54,13 +55,12 @@ Grid.defaultProps = {
   alignItems: undefined,
   autoFlow: undefined,
   children: null,
-  columnGap: undefined,
-  columns: undefined,
-  id: undefined,
+  columnGap: 4,
+  columns: '1fr',
   justifyContent: undefined,
   justifyItems: undefined,
-  rowGap: undefined,
-  rows: undefined,
+  rowGap: 4,
+  rows: 'auto',
   tag: 'div',
 };
 
@@ -118,19 +118,19 @@ Grid.propTypes = {
    */
   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.
+   * Gap between columns. Accepts any of [spacing values](/foundation/spacing-values) as number.
+   * See [MDN](https://developer.mozilla.org/en-US/docs/Web/CSS/column-gap) for more about `column-gap`.
    */
   columnGap: PropTypes.oneOfType([
-    PropTypes.string,
+    PropTypes.oneOf(SPACING_VALUES),
     PropTypes.shape({
-      xs: PropTypes.string,
-      sm: PropTypes.string,
-      md: PropTypes.string,
-      lg: PropTypes.string,
-      xl: PropTypes.string,
-      x2l: PropTypes.string,
-      x3l: PropTypes.string,
+      xs: PropTypes.oneOf(SPACING_VALUES),
+      sm: PropTypes.oneOf(SPACING_VALUES),
+      md: PropTypes.oneOf(SPACING_VALUES),
+      lg: PropTypes.oneOf(SPACING_VALUES),
+      xl: PropTypes.oneOf(SPACING_VALUES),
+      x2l: PropTypes.oneOf(SPACING_VALUES),
+      x3l: PropTypes.oneOf(SPACING_VALUES),
     }),
   ]),
   /**
@@ -149,10 +149,6 @@ Grid.propTypes = {
       x3l: PropTypes.string,
     }),
   ]),
-  /**
-   * ID of the root HTML element.
-   */
-  id: PropTypes.string,
   /**
    * Content justification. Accepts any valid value of `justify-content` CSS property.
    * See [MDN](https://developer.mozilla.org/en-US/docs/Web/CSS/justify-content) for more.
@@ -186,19 +182,19 @@ Grid.propTypes = {
     }),
   ]),
   /**
-   * 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.
+   * Gap between rows. Accepts any of [spacing values](/foundation/spacing-values) as number.
+   * See [MDN](https://developer.mozilla.org/en-US/docs/Web/CSS/row-gap) for more about `row-gap`.
    */
   rowGap: PropTypes.oneOfType([
-    PropTypes.string,
+    PropTypes.oneOf(SPACING_VALUES),
     PropTypes.shape({
-      xs: PropTypes.string,
-      sm: PropTypes.string,
-      md: PropTypes.string,
-      lg: PropTypes.string,
-      xl: PropTypes.string,
-      x2l: PropTypes.string,
-      x3l: PropTypes.string,
+      xs: PropTypes.oneOf(SPACING_VALUES),
+      sm: PropTypes.oneOf(SPACING_VALUES),
+      md: PropTypes.oneOf(SPACING_VALUES),
+      lg: PropTypes.oneOf(SPACING_VALUES),
+      xl: PropTypes.oneOf(SPACING_VALUES),
+      x2l: PropTypes.oneOf(SPACING_VALUES),
+      x3l: PropTypes.oneOf(SPACING_VALUES),
     }),
   ]),
   /**

package/src/lib/components/Grid/Grid.scss

@@ -22,22 +22,22 @@
 
 @use "sass:map";
 @use "../../styles/tools/spacing";
-@use "theme";
+@use "settings";
 @use "tools";
 
 .root {
-    @include tools.assign-responsive-custom-properties(theme.$responsive-properties); // 1.
+    @include tools.assign-responsive-custom-properties(settings.$grid-responsive-properties); // 1.
     @include spacing.bottom(layouts);
 
     display: grid;
     grid-template-columns: var(--rui-local-columns); // 2.
     grid-template-rows: var(--rui-local-rows); // 2.
-    grid-auto-flow: var(--rui-local-auto-flow, #{map.get(theme.$responsive-properties, auto-flow)}); // 2.
+    grid-auto-flow: var(--rui-local-auto-flow); // 2.
     grid-gap: var(--rui-local-row-gap) var(--rui-local-column-gap); // 2.
-    align-content: var(--rui-local-align-content, #{map.get(theme.$responsive-properties, align-content)}); // 2.
-    align-items: var(--rui-local-align-items, #{map.get(theme.$responsive-properties, align-items)}); // 2.
-    justify-content: var(--rui-local-justify-content, #{map.get(theme.$responsive-properties, justify-content)}); // 2.
-    justify-items: var(--rui-local-justify-items, #{map.get(theme.$responsive-properties, justify-items)}); // 2.
+    align-content: var(--rui-local-align-content); // 2.
+    align-items: var(--rui-local-align-items); // 2.
+    justify-content: var(--rui-local-justify-content); // 2.
+    justify-items: var(--rui-local-justify-items); // 2.
 }
 
 // stylelint-disable-next-line selector-max-universal -- Reset any previously added margins.
@@ -46,15 +46,10 @@
 }
 
 .span {
-    $responsive-properties: (
-        column-span: 1,
-        row-span: 1,
-    );
+    @include tools.assign-responsive-custom-properties(settings.$grid-span-responsive-properties); // 1.
 
-    @include tools.assign-responsive-custom-properties($responsive-properties); // 1.
-
-    grid-column: span var(--rui-local-column-span, 1); // 2.
-    grid-row: span var(--rui-local-row-span, 1); // 2.
+    grid-column: span var(--rui-local-column-span); // 2.
+    grid-row: span var(--rui-local-row-span); // 2.
 }
 
 // stylelint-disable selector-no-qualifying-type

package/src/lib/components/Grid/GridSpan.jsx

@@ -2,16 +2,16 @@ import PropTypes from 'prop-types';
 import React from 'react';
 import { withGlobalProps } from '../../provider';
 import { isChildrenEmpty } from '../_helpers/isChildrenEmpty';
+import { transferProps } from '../_helpers/transferProps';
 import { generateResponsiveCustomProperties } from './_helpers/generateResponsiveCustomProperties';
 import styles from './Grid.scss';
 
 export const GridSpan = ({
   children,
   columns,
-  id,
   rows,
   tag: Tag,
-  ...other
+  ...restProps
 }) => {
   if (isChildrenEmpty(children)) {
     return null;
@@ -19,13 +19,12 @@ export const GridSpan = ({
 
   return (
     <Tag
-      id={id}
+      {...transferProps(restProps)}
       className={styles.span}
       style={{
         ...generateResponsiveCustomProperties(columns, 'column-span'),
         ...generateResponsiveCustomProperties(rows, 'row-span'),
       }}
-      {...other}
     >
       {children}
     </Tag>
@@ -37,9 +36,8 @@ export const GridSpan = ({
 
 GridSpan.defaultProps = {
   children: null,
-  columns: undefined,
-  id: undefined,
-  rows: undefined,
+  columns: 1,
+  rows: 1,
   tag: 'div',
 };
 
@@ -63,10 +61,6 @@ GridSpan.propTypes = {
       x3l: PropTypes.number,
     }),
   ]),
-  /**
-   * ID of the root HTML element.
-   */
-  id: PropTypes.string,
   /**
    * Number of rows to span.
    */

package/src/lib/components/Grid/README.mdx

@@ -11,8 +11,10 @@ import {
   Props,
 } from 'docz'
 import { Placeholder } from '../../../docs/_components/Placeholder/Placeholder'
-import { Grid } from './Grid'
-import { GridSpan } from './GridSpan'
+import {
+  Grid,
+  GridSpan,
+} from '../..'
 
 The responsive Grid layout aligns content into an organized grid.
 
@@ -38,12 +40,11 @@ See [API](#api) for all available options.
 
 ## General Guidelines
 
-- This component implements native [CSS grid layout][grid-layout], a powerful
-  tool for two-dimensional layouts. You may use any value accepted by
-  [grid-template-columns], [grid-template-rows], [grid-column-gap],
-  [grid-row-gap], [grid-auto-flow], [align-content], [align-items],
-  [justify-content], [justify-items], and CSS properties in corresponding API
-  options of the component.
+- This component implements the native [CSS grid layout][grid-layout], a
+  powerful tool for two-dimensional layouts. You may use any value accepted by
+  [grid-template-columns], [grid-template-rows], [grid-auto-flow],
+  [align-content], [align-items], [justify-content], [justify-items], and CSS
+  properties in corresponding API options of the component.
 
 - To align your items in the grid, **simply wrap** them with the Grid
   component. Unlike other grid frameworks and UI libraries, **no additional
@@ -62,7 +63,7 @@ See [API](#api) for all available options.
 ## Columns
 
 Stack is the default outcome of Grid. Use the `columns` option to organize your
-items into grid.
+items into a grid.
 
 <Playground>
   <Grid columns="1fr 1fr 1fr">
@@ -89,7 +90,9 @@ You can use the [`repeat()`][repeat] function to specify a recurring pattern.
 </Playground>
 
 Combine `repeat()` with `auto-fit` and [`minmax()`][minmax] to build automatic
-responsive layouts. Resize the playground to see it in action.
+responsive layouts.
+
+📐 Try resizing the playground to see it in action.
 
 <Playground>
   <Grid columns="repeat(auto-fit, minmax(200px, auto))">
@@ -102,8 +105,8 @@ responsive layouts. Resize the playground to see it in action.
   </Grid>
 </Playground>
 
-👉 If you need your items to have **equal height** even with content of varying
-length, it may be necessary to set `height: 100%` on them.
+👉 If you need your items to have **equal height** even with the content of
+varying lengths, it may be necessary to set `height: 100%` on them.
 
 ## Rows
 
@@ -122,10 +125,11 @@ Use `columns` and `rows` to specify a more complicated grid layout.
 
 ## Gaps
 
-Both column and row gaps can be customized.
+Both column and row gaps can be customized. The value must correspond to any of
+[available spacings](/foundation/spacing).
 
 <Playground>
-  <Grid columns="repeat(3, 1fr)" columnGap="0.75rem" rowGap="2rem">
+  <Grid columns="repeat(3, 1fr)" columnGap={2} rowGap={6}>
     <Placeholder bordered>Grid item</Placeholder>
     <Placeholder bordered>Grid item</Placeholder>
     <Placeholder bordered>Grid item</Placeholder>
@@ -137,7 +141,7 @@ Both column and row gaps can be customized.
 
 ## Alignment
 
-Individual items and the entire grid content can be aligned and along both axes.
+Individual items and the entire grid content can be aligned along both axes.
 
 <Playground>
   <Grid
@@ -157,8 +161,8 @@ Individual items and the entire grid content can be aligned and along both axes.
 
 ## Custom HTML Tag
 
-To render as list for example, just change the output `tag` to `ul` or `ol` and
-wrap your items with `<li>`.
+To render as a list, for example, just change the output `tag` to `ul` or `ol`
+and wrap your items with `<li>`.
 
 <Playground>
   <Grid tag="ul">
@@ -180,9 +184,11 @@ If you need to build more complicated layouts, you have full control over the
 grid definition. Just specify your grid layout for
 [breakpoints](/foundation/breakpoints) where a change of layout is needed.
 The Grid component is written with the mobile-first approach so values for small
-breakpoints are used until they're overridden by a bigger breakpoint. If `xs`
-settings are omitted, theme defaults are used. Resize your browser to see how it
-works.
+breakpoints are used until they're overridden by a bigger breakpoint.
+
+👉 With this syntax there are no defaults for individual breakpoints.
+
+📐 Try resizing your browser to see how it works.
 
 <Playground>
   <Grid
@@ -191,16 +197,17 @@ works.
       md: '1fr 2fr',
     }}
     columnGap={{
-      md: 'var(--rui-spacing-2)',
-      lg: 'var(--rui-spacing-4)',
+      xs: 4,
+      md: 2,
+      lg: 4,
     }}
     rows={{
       xs: 'auto auto 200px 200px',
       md: 'auto 200px auto',
     }}
     rowGap={{
-      xs: 'var(--rui-spacing-3)',
-      md: 'var(--rui-spacing-4)',
+      xs: 3,
+      md: 4,
     }}
   >
     <Placeholder bordered>Grid item</Placeholder>
@@ -214,9 +221,9 @@ works.
 
 ## Advanced Layouts
 
-Wrap your content with GridSpan component to span it over multiple columns or
-rows. Use the `autoFlow` option to control the layout when combined with
-responsive columns and rows.
+Wrap your content with the GridSpan component to span it over multiple
+columns or rows. Use the `autoFlow` option to control the layout when combined
+with responsive columns and rows.
 
 <Playground>
   <Grid
@@ -256,6 +263,17 @@ responsive columns and rows.
 👉 `autoFlow` (used in the example above) implements the `grid-auto-flow` CSS
 property. Check [MDN][grid-auto-flow] to fully understand available options.
 
+## Forwarding HTML Attributes
+
+In addition to the options below in the [component's API](#api) section, you
+can specify [React synthetic events] or **any HTML attribute you like.** All
+attributes that don't interfere with the API are forwarded to the HTML element
+of your choice provided by `tag`, which is `<div>` by default. It enables making
+the component interactive and helps to improve its accessibility.
+
+👉 Refer to the MDN reference for the full list of supported attributes of the
+[div] element or [any other][all-html-elements] element of your choice.
+
 ## API
 
 <Props table of={Grid} />
@@ -266,18 +284,9 @@ Wrapper for content that should span multiple rows or columns.
 
 <Props table of={GridSpan} />
 
-## Theming
-
-| Custom Property                                      | Description                                                  |
-|------------------------------------------------------|--------------------------------------------------------------|
-| `--rui-Grid__column-gap`                             | Default column gap                                           |
-| `--rui-Grid__row-gap`                                | Default row gap                                              |
-
 [grid-layout]: https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Grid_Layout
 [grid-template-columns]: https://developer.mozilla.org/en-US/docs/Web/CSS/grid-template-columns
 [grid-template-rows]: https://developer.mozilla.org/en-US/docs/Web/CSS/grid-template-rows
-[grid-column-gap]: https://developer.mozilla.org/en-US/docs/Web/CSS/column-gap
-[grid-row-gap]: https://developer.mozilla.org/en-US/docs/Web/CSS/row-gap
 [grid-auto-flow]: https://developer.mozilla.org/en-US/docs/Web/CSS/grid-auto-flow
 [align-content]: https://developer.mozilla.org/en-US/docs/Web/CSS/align-content
 [align-items]: https://developer.mozilla.org/en-US/docs/Web/CSS/align-items
@@ -285,3 +294,6 @@ Wrapper for content that should span multiple rows or columns.
 [justify-items]: https://developer.mozilla.org/en-US/docs/Web/CSS/justify-items
 [repeat]: https://developer.mozilla.org/en-US/docs/Web/CSS/repeat
 [minmax]: https://developer.mozilla.org/en-US/docs/Web/CSS/minmax
+[React synthetic events]: https://reactjs.org/docs/events.html
+[div]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/div#attributes
+[all-html-elements]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element

package/src/lib/components/Grid/_helpers/generateResponsiveCustomProperties.js

@@ -1,14 +1,22 @@
-export const generateResponsiveCustomProperties = (prop, infix) => {
+const prepareValueByType = (value, type) => {
+  if (type === 'spacing') {
+    return `var(--rui-spacing-${value})`;
+  }
+
+  return value;
+};
+
+export const generateResponsiveCustomProperties = (prop, infix, type = null) => {
   if (typeof prop === 'undefined') {
     return null;
   }
 
   if (typeof prop !== 'object') {
-    return { [`--rui-local-${infix}-xs`]: prop };
+    return { [`--rui-local-${infix}-xs`]: prepareValueByType(prop, type) };
   }
 
   return Object.keys(prop).reduce((acc, breakpoint) => ({
     ...acc,
-    [`--rui-local-${infix}-${breakpoint}`]: prop[breakpoint],
+    [`--rui-local-${infix}-${breakpoint}`]: prepareValueByType(prop[breakpoint], type),
   }), {});
 };

package/src/lib/components/Grid/_settings.scss

@@ -0,0 +1,18 @@
+$grid-responsive-properties: [
+    columns,
+    column-gap,
+    rows,
+    row-gap,
+    auto-flow,
+    align-content,
+    align-items,
+    justify-content,
+    justify-items,
+]; // stylelint-disable-line indentation -- Broken rule?
+
+$grid-span-responsive-properties: [
+    column-span,
+    row-span,
+]; // stylelint-disable-line indentation -- Broken rule?
+
+$initial-fallback-value: initial;

package/src/lib/components/Grid/_tools.scss

@@ -1,14 +1,14 @@
 @use "sass:map";
 @use "../../styles/settings/breakpoints";
 @use "../../styles/tools/breakpoint";
+@use "settings";
 
 // Generate fallback cascade using `var()` function fallbacks.
 //
 // $property-name: <string> Custom property name
-// $initial-fallback: <string> Initial fallback value
 // $current-breakpoint: <one of $breakpoint-values> Generate cascade for breakpoints smaller than this one
-@function _generate-custom-property-fallback-cascade($property-name, $initial-fallback, $current-breakpoint) {
-    $fallback-cascade: $initial-fallback;
+@function _generate-custom-property-fallback-cascade($property-name, $current-breakpoint) {
+    $fallback-cascade: settings.$initial-fallback-value;
 
     @each $breakpoint in map.keys(breakpoints.$values) {
         @if $breakpoint == $current-breakpoint {
@@ -26,11 +26,11 @@
 @mixin assign-responsive-custom-properties($properties) {
     @each $breakpoint in map.keys(breakpoints.$values) {
         @include breakpoint.up($breakpoint) {
-            @each $property-name, $initial-fallback in $properties {
+            @each $property-name in $properties {
                 --rui-local-#{$property-name}:
                     var(
                         --rui-local-#{$property-name}-#{$breakpoint},
-                        #{_generate-custom-property-fallback-cascade($property-name, $initial-fallback, $breakpoint)}
+                        #{_generate-custom-property-fallback-cascade($property-name, $breakpoint)}
                     );
             }
         }