@react-ui-org/react-ui 0.52.1 → 0.54.0

package/src/components/Grid/README.md

@@ -0,0 +1,281 @@
+# Grid
+
+The responsive Grid layout aligns content into an organized grid.
+
+## Basic Usage
+
+To implement the Grid component, you need to import it first:
+
+```js
+import { Grid } from '@react-ui-org/react-ui';
+```
+
+And use it:
+
+```docoff-react-preview
+<Grid>
+  <docoff-placeholder bordered>Grid item</docoff-placeholder>
+  <docoff-placeholder bordered>Grid item</docoff-placeholder>
+  <docoff-placeholder bordered>Grid item</docoff-placeholder>
+</Grid>
+```
+
+See [API](#api) for all available options.
+
+## General Guidelines
+
+- 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
+  markup** like GridItem or Cell is necessary for your items. But it's there
+  when you really need it—see [Advanced Layouts](#advanced-layouts).
+
+- For forms, use rather the [FormLayout](/components/FormLayout) component
+  which is designed specifically for that purpose.
+
+- The Grid component is so powerful that it enables you to build even very
+  advanced layouts **without** having to write **a single line of custom CSS.**
+  See [Advanced Layouts](#advanced-layouts) for more.
+
+👉 Vertical margin of items inside Grid is reset to zero.
+
+## Columns
+
+Stack is the default outcome of Grid. Use the `columns` option to organize your
+items into a grid.
+
+```docoff-react-preview
+<Grid columns="1fr 1fr 1fr">
+  <docoff-placeholder bordered>Grid item</docoff-placeholder>
+  <docoff-placeholder bordered>Grid item</docoff-placeholder>
+  <docoff-placeholder bordered>Grid item</docoff-placeholder>
+  <docoff-placeholder bordered>Grid item</docoff-placeholder>
+  <docoff-placeholder bordered>Grid item</docoff-placeholder>
+  <docoff-placeholder bordered>Grid item</docoff-placeholder>
+</Grid>
+```
+
+You can use the [`repeat()`][repeat] function to specify a recurring pattern.
+
+```docoff-react-preview
+<Grid columns="repeat(3, 1fr)">
+  <docoff-placeholder bordered>Grid item</docoff-placeholder>
+  <docoff-placeholder bordered>Grid item</docoff-placeholder>
+  <docoff-placeholder bordered>Grid item</docoff-placeholder>
+  <docoff-placeholder bordered>Grid item</docoff-placeholder>
+  <docoff-placeholder bordered>Grid item</docoff-placeholder>
+  <docoff-placeholder bordered>Grid item</docoff-placeholder>
+</Grid>
+```
+
+Combine `repeat()` with `auto-fit` and [`minmax()`][minmax] to build automatic
+responsive layouts.
+
+```docoff-react-preview
+<Grid columns="repeat(auto-fit, minmax(200px, auto))">
+  <docoff-placeholder bordered>Grid item</docoff-placeholder>
+  <docoff-placeholder bordered>Grid item</docoff-placeholder>
+  <docoff-placeholder bordered>Grid item</docoff-placeholder>
+  <docoff-placeholder bordered>Grid item</docoff-placeholder>
+  <docoff-placeholder bordered>Grid item</docoff-placeholder>
+  <docoff-placeholder bordered>Grid item</docoff-placeholder>
+</Grid>
+```
+
+👉 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
+
+Use `columns` and `rows` to specify a more complicated grid layout.
+
+```docoff-react-preview
+<Grid columns="1fr 2fr" rows="auto 200px auto">
+  <docoff-placeholder bordered>Grid item</docoff-placeholder>
+  <docoff-placeholder bordered>Grid item</docoff-placeholder>
+  <docoff-placeholder bordered>Grid item</docoff-placeholder>
+  <docoff-placeholder bordered>Grid item</docoff-placeholder>
+  <docoff-placeholder bordered>Grid item</docoff-placeholder>
+  <docoff-placeholder bordered>Grid item</docoff-placeholder>
+</Grid>
+```
+
+## Gaps
+
+Both column and row gaps can be customized. The value must correspond to any of
+[available spacings](/docs/foundation/spacing).
+
+```docoff-react-preview
+<Grid columns="repeat(3, 1fr)" columnGap={2} rowGap={6}>
+  <docoff-placeholder bordered>Grid item</docoff-placeholder>
+  <docoff-placeholder bordered>Grid item</docoff-placeholder>
+  <docoff-placeholder bordered>Grid item</docoff-placeholder>
+  <docoff-placeholder bordered>Grid item</docoff-placeholder>
+  <docoff-placeholder bordered>Grid item</docoff-placeholder>
+  <docoff-placeholder bordered>Grid item</docoff-placeholder>
+</Grid>
+```
+
+## Alignment
+
+Individual items and the entire grid content can be aligned along both axes.
+
+```docoff-react-preview
+<Grid
+  columns="repeat(3, 10em)"
+  alignItems="center"
+  justifyItems="center"
+  justifyContent="center"
+>
+  <docoff-placeholder bordered>Grid item</docoff-placeholder>
+  <docoff-placeholder bordered>Grid item<br /> with two lines</docoff-placeholder>
+  <docoff-placeholder bordered>Grid item</docoff-placeholder>
+  <docoff-placeholder bordered>Grid item</docoff-placeholder>
+  <docoff-placeholder bordered>Grid item</docoff-placeholder>
+  <docoff-placeholder bordered>Grid item</docoff-placeholder>
+</Grid>
+```
+
+## Custom HTML Tag
+
+To render as a list, for example, just change the output `tag` to `ul` or `ol`
+and wrap your items with `<li>`.
+
+```docoff-react-preview
+<Grid tag="ul">
+  <li>
+    <docoff-placeholder bordered>List item</docoff-placeholder>
+  </li>
+  <li>
+    <docoff-placeholder bordered>List item</docoff-placeholder>
+  </li>
+  <li>
+    <docoff-placeholder bordered>List item</docoff-placeholder>
+  </li>
+</Grid>
+```
+
+## Media Queries
+
+If you need to build more complicated layouts, you have full control over the
+grid definition. Just specify your grid layout for
+[breakpoints](/docs/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.
+
+👉 With this syntax there are no defaults for individual breakpoints.
+
+📐 Try resizing your browser to see how it works.
+
+```docoff-react-preview
+<Grid
+  columns={{
+    xs: '1fr',
+    md: '1fr 2fr',
+  }}
+  columnGap={{
+    xs: 4,
+    md: 2,
+    lg: 4,
+  }}
+  rows={{
+    xs: 'auto auto 200px 200px',
+    md: 'auto 200px auto',
+  }}
+  rowGap={{
+    xs: 3,
+    md: 4,
+  }}
+>
+  <docoff-placeholder bordered>Grid item</docoff-placeholder>
+  <docoff-placeholder bordered>Grid item</docoff-placeholder>
+  <docoff-placeholder bordered>Grid item</docoff-placeholder>
+  <docoff-placeholder bordered>Grid item</docoff-placeholder>
+  <docoff-placeholder bordered>Grid item</docoff-placeholder>
+  <docoff-placeholder bordered>Grid item</docoff-placeholder>
+</Grid>
+```
+
+## Advanced Layouts
+
+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.
+
+```docoff-react-preview
+<Grid
+  autoFlow={{
+    xs: 'row dense',
+    sm: 'column',
+  }}
+  columns={{
+    xs: 'repeat(2, 1fr)',
+    sm: 'repeat(4, 1fr)',
+  }}
+  rows={{
+    xs: 'repeat(8, 50px)',
+    sm: 'auto 100px auto auto',
+  }}
+>
+  <docoff-placeholder bordered>Grid item 1</docoff-placeholder>
+  <docoff-placeholder bordered>Grid item 2</docoff-placeholder>
+  <docoff-placeholder bordered>Grid item 3</docoff-placeholder>
+  <docoff-placeholder bordered>Grid item 4</docoff-placeholder>
+  <docoff-placeholder bordered>Grid item 5</docoff-placeholder>
+  <GridSpan columns={2} rows={2}>
+    <docoff-placeholder bordered height="100%">
+      Grid item spanning over two lines and two rows
+    </docoff-placeholder>
+  </GridSpan>
+  <docoff-placeholder bordered>Grid item 6</docoff-placeholder>
+  <docoff-placeholder bordered>Grid item 7</docoff-placeholder>
+  <docoff-placeholder bordered>Grid item 8</docoff-placeholder>
+  <docoff-placeholder bordered>Grid item 9</docoff-placeholder>
+  <docoff-placeholder bordered>Grid item 10</docoff-placeholder>
+  <docoff-placeholder bordered>Grid item 11</docoff-placeholder>
+  <docoff-placeholder bordered>Grid item 12</docoff-placeholder>
+</Grid>
+```
+
+👉 `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
+
+<docoff-react-props src="/components/Grid/Grid.jsx"></docoff-react-props>
+
+### GridSpan API
+
+Wrapper for content that should span multiple rows or columns.
+
+<docoff-react-props src="/components/Grid/GridSpan.jsx"></docoff-react-props>
+
+[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-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
+[justify-content]: https://developer.mozilla.org/en-US/docs/Web/CSS/justify-content
+[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 → components}/InputGroup/InputGroup.jsx

@@ -1,5 +1,8 @@
 import PropTypes from 'prop-types';
-import React, { useContext } from 'react';
+import React, {
+  useContext,
+  useMemo,
+} from 'react';
 import { Text } from '../Text';
 import { withGlobalProps } from '../../provider';
 import { classNames } from '../../utils/classNames';
@@ -19,11 +22,17 @@ export const InputGroup = ({
   isLabelVisible,
   label,
   layout,
+  required,
   size,
   validationTexts,
   ...restProps
 }) => {
   const formLayoutContext = useContext(FormLayoutContext);
+  const inputGroupContextValue = useMemo(() => ({
+    disabled,
+    layout,
+    size,
+  }), [disabled, layout, size]);
 
   if (isChildrenEmpty(children)) {
     return null;
@@ -42,7 +51,6 @@ export const InputGroup = ({
   return (
     <fieldset
       {...transferProps(restProps)}
-      id={id}
       className={classNames(
         styles.root,
         formLayoutContext && styles.isRootInFormLayout,
@@ -50,10 +58,12 @@ export const InputGroup = ({
           ? styles.isRootLayoutHorizontal
           : styles.isRootLayoutVertical,
         disabled && styles.isRootDisabled,
+        required && styles.isRootRequired,
         getRootSizeClassName(size, styles),
         getRootValidationStateClassName(validationState, styles),
       )}
       disabled={disabled}
+      id={id}
     >
       <legend
         className={styles.legend}
@@ -61,28 +71,21 @@ export const InputGroup = ({
       >
         {label}
       </legend>
-      <div
-        aria-hidden
-        className={classNames(
-          styles.label,
-          !isLabelVisible && styles.isLabelHidden,
-        )}
-        id={id && `${id}__displayLabel`}
-      >
-        {label}
-      </div>
+      {isLabelVisible && (
+        <div
+          aria-hidden
+          className={styles.label}
+          id={id && `${id}__displayLabel`}
+        >
+          {label}
+        </div>
+      )}
       <div className={styles.field}>
         <div
           className={styles.inputGroup}
           id={id && `${id}__group`}
         >
-          <InputGroupContext.Provider
-            value={{
-              disabled,
-              layout,
-              size,
-            }}
-          >
+          <InputGroupContext.Provider value={inputGroupContextValue}>
             {children}
           </InputGroupContext.Provider>
         </div>
@@ -111,6 +114,7 @@ InputGroup.defaultProps = {
   id: undefined,
   isLabelVisible: true,
   layout: 'vertical',
+  required: false,
   size: 'medium',
   validationTexts: null,
 };
@@ -155,6 +159,11 @@ InputGroup.propTypes = {
    * as the value is inherited in such case.
    */
   layout: PropTypes.oneOf(['horizontal', 'vertical']),
+  /**
+   * If `true`, the `InputGroup`'s label appears as required. Underlying `<fieldset>`
+   * element does not take `required` attribute so there is no functional effect.
+   */
+  required: PropTypes.bool,
   /**
    * Size of the `children` elements.
    */

package/src/{lib/components → components}/InputGroup/InputGroup.scss

@@ -41,6 +41,10 @@
     @include foundation.help-text();
 }
 
+.isRootRequired .label {
+    @include foundation.label-required();
+}
+
 // States
 .isRootStateInvalid {
     @include variants.validation(invalid);
@@ -54,11 +58,6 @@
     @include variants.validation(warning);
 }
 
-// Invisible label
-.isLabelHidden {
-    @include accessibility.hide-text();
-}
-
 // Layouts
 .isRootLayoutVertical,
 .isRootLayoutHorizontal {