@react-ui-org/react-ui 0.42.0 → 0.44.0

package/src/lib/components/{layout/Grid → Grid}/Grid.jsx

@@ -1,6 +1,6 @@
 import PropTypes from 'prop-types';
 import React from 'react';
-import { withProviderContext } from '../../../provider';
+import { withProviderContext } from '../../provider';
 import { generateResponsiveCustomProperties } from './helpers/generateResponsiveCustomProperties';
 import styles from './Grid.scss';
 
@@ -16,6 +16,7 @@ export const Grid = ({
   justifyItems,
   rowGap,
   rows,
+  tag: Tag,
   ...other
 }) => {
   if (!children) {
@@ -23,15 +24,15 @@ export const Grid = ({
   }
 
   return (
-    <div
+    <Tag
       id={id}
       className={styles.root}
       style={{
-        ...(typeof autoFlow !== 'undefined' ? { '--rui-local-auto-flow': autoFlow } : {}),
         ...generateResponsiveCustomProperties(columns, 'columns'),
         ...generateResponsiveCustomProperties(columnGap, 'column-gap'),
         ...generateResponsiveCustomProperties(rows, 'rows'),
         ...generateResponsiveCustomProperties(rowGap, 'row-gap'),
+        ...generateResponsiveCustomProperties(autoFlow, 'auto-flow'),
         ...generateResponsiveCustomProperties(alignContent, 'align-content'),
         ...generateResponsiveCustomProperties(alignItems, 'align-items'),
         ...generateResponsiveCustomProperties(justifyContent, 'justify-content'),
@@ -40,7 +41,7 @@ export const Grid = ({
       {...other}
     >
       {children}
-    </div>
+    </Tag>
   );
 };
 
@@ -59,6 +60,7 @@ Grid.defaultProps = {
   justifyItems: undefined,
   rowGap: undefined,
   rows: undefined,
+  tag: 'div',
 };
 
 Grid.propTypes = {
@@ -98,7 +100,18 @@ 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']),
+  autoFlow: PropTypes.oneOfType([
+    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,
+    }),
+  ]),
   /**
    * Items to be aligned in the grid.
    */
@@ -203,6 +216,11 @@ Grid.propTypes = {
       xxxl: PropTypes.string,
     }),
   ]),
+  /**
+   * HTML tag to render. Can be any valid HTML tag of your choice, usually a
+   * [block-level element](https://developer.mozilla.org/en-US/docs/Web/HTML/Block-level_elements).
+   */
+  tag: PropTypes.string,
 };
 
 export const GridWithContext = withProviderContext(Grid, 'Grid');

package/src/lib/components/{layout/Grid → Grid}/Grid.scss

@@ -19,11 +19,9 @@
 //    `--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.
 
 @use 'sass:map';
-@use '../../../styles/tools/spacing';
+@use '../../styles/tools/spacing';
 @use 'theme';
 @use 'tools';
 
@@ -34,7 +32,7 @@
   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, theme.$auto-flow); // 3.
+  grid-auto-flow: var(--rui-local-auto-flow, #{map.get(theme.$responsive-properties, 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.

package/src/lib/components/{layout/Grid → Grid}/GridSpan.jsx

@@ -1,6 +1,6 @@
 import PropTypes from 'prop-types';
 import React from 'react';
-import { withProviderContext } from '../../../provider';
+import { withProviderContext } from '../../provider';
 import { generateResponsiveCustomProperties } from './helpers/generateResponsiveCustomProperties';
 import styles from './Grid.scss';
 
@@ -9,6 +9,7 @@ export const GridSpan = ({
   columns,
   id,
   rows,
+  tag: Tag,
   ...other
 }) => {
   if (!children) {
@@ -16,7 +17,7 @@ export const GridSpan = ({
   }
 
   return (
-    <div
+    <Tag
       id={id}
       className={styles.span}
       style={{
@@ -26,7 +27,7 @@ export const GridSpan = ({
       {...other}
     >
       {children}
-    </div>
+    </Tag>
   );
 };
 
@@ -38,6 +39,7 @@ GridSpan.defaultProps = {
   columns: undefined,
   id: undefined,
   rows: undefined,
+  tag: 'div',
 };
 
 GridSpan.propTypes = {
@@ -79,6 +81,11 @@ GridSpan.propTypes = {
       xxxl: PropTypes.number,
     }),
   ]),
+  /**
+   * HTML tag to render. Can be any valid HTML tag of your choice, usually a
+   * [block-level element](https://developer.mozilla.org/en-US/docs/Web/HTML/Block-level_elements).
+   */
+  tag: PropTypes.string,
 };
 
 export const GridSpanWithContext = withProviderContext(GridSpan, 'GridSpan');

package/src/lib/components/{layout/Grid → Grid}/README.mdx

@@ -1,7 +1,7 @@
 ---
 name: Grid
 menu: 'Layouts'
-route: /components/layout/grid
+route: /components/grid
 ---
 
 # Grid
@@ -10,7 +10,7 @@ import {
   Playground,
   Props,
 } from 'docz'
-import { Placeholder } from '../../../../docs/_components/Placeholder/Placeholder'
+import { Placeholder } from '../../../docs/_components/Placeholder/Placeholder'
 import { Grid } from './Grid'
 import { GridSpan } from './GridSpan'
 
@@ -41,20 +41,12 @@ See [API](#api) for all available options.
 
 ## General Guidelines
 
-- This component implements native
-  [CSS grid layout](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Grid_Layout),
-  the right CSS tool for two-dimensional layouts. You may use any value accepted
-  by
-  [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),
-  [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)
-  and CSS properties in corresponding API options of the component.
+- This component implements native [CSS grid layout][grid-layout], the right CSS
+  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.
 
 - To align your items in the grid, **simply wrap** them with the Grid
   component. Unlike other grid frameworks and UI libraries, **no additional
@@ -84,9 +76,7 @@ Use `columns` and `rows` to specify your grid layout.
   </Grid>
 </Playground>
 
-You can use the
-[`repeat()`](https://developer.mozilla.org/en-US/docs/Web/CSS/repeat) function
-to specify a recurring pattern.
+You can use the [`repeat()`][repeat] function to specify a recurring pattern.
 
 <Playground>
   <Grid columns="repeat(3, 1fr)">
@@ -99,9 +89,8 @@ to specify a recurring pattern.
   </Grid>
 </Playground>
 
-Combine `repeat()` with `auto-fit` and
-[`minmax()`](https://developer.mozilla.org/en-US/docs/Web/CSS/minmax) to build
-automatic responsive layouts. Resize the playground to see it in action.
+Combine `repeat()` with `auto-fit` and [`minmax()`][minmax] to build automatic
+responsive layouts. Resize the playground to see it in action.
 
 <Playground>
   <Grid columns="repeat(auto-fit, minmax(200px, auto))">
@@ -198,7 +187,10 @@ responsive columns and rows.
 
 <Playground>
   <Grid
-    autoFlow="row dense"
+    autoFlow={{
+      xs: 'row dense',
+      sm: 'column',
+    }}
     columns={{
       xs: 'repeat(2, 1fr)',
       sm: 'repeat(4, 1fr)',
@@ -208,29 +200,28 @@ responsive columns and rows.
       sm: 'auto 100px auto auto',
     }}
   >
-    <Placeholder bordered>Grid item</Placeholder>
-    <Placeholder bordered>Grid item</Placeholder>
-    <Placeholder bordered>Grid item</Placeholder>
-    <Placeholder bordered>Grid item</Placeholder>
-    <Placeholder bordered>Grid item</Placeholder>
+    <Placeholder bordered>Grid item 1</Placeholder>
+    <Placeholder bordered>Grid item 2</Placeholder>
+    <Placeholder bordered>Grid item 3</Placeholder>
+    <Placeholder bordered>Grid item 4</Placeholder>
+    <Placeholder bordered>Grid item 5</Placeholder>
     <GridSpan columns={2} rows={2}>
       <Placeholder bordered height="100%">
         Grid item spanning over two lines and two rows
       </Placeholder>
     </GridSpan>
-    <Placeholder bordered>Grid item</Placeholder>
-    <Placeholder bordered>Grid item</Placeholder>
-    <Placeholder bordered>Grid item</Placeholder>
-    <Placeholder bordered>Grid item</Placeholder>
-    <Placeholder bordered>Grid item</Placeholder>
-    <Placeholder bordered>Grid item</Placeholder>
-    <Placeholder bordered>Grid item</Placeholder>
+    <Placeholder bordered>Grid item 6</Placeholder>
+    <Placeholder bordered>Grid item 7</Placeholder>
+    <Placeholder bordered>Grid item 8</Placeholder>
+    <Placeholder bordered>Grid item 9</Placeholder>
+    <Placeholder bordered>Grid item 10</Placeholder>
+    <Placeholder bordered>Grid item 11</Placeholder>
+    <Placeholder bordered>Grid item 12</Placeholder>
   </Grid>
 </Playground>
 
-👉 `autoFlow` implements the `grid-auto-flow` CSS property. See
-[MDN](https://developer.mozilla.org/en-US/docs/Web/CSS/grid-auto-flow) to fully
-understand available options.
+👉 `autoFlow` (used in the example above) implements the `grid-auto-flow` CSS
+property. Check [MDN][grid-auto-flow] to fully understand available options.
 
 ## API
 
@@ -255,3 +246,16 @@ Wrapper for content that should span multiple rows or columns.
 | `--rui-Grid__justify-content`                        | Default horizontal alignment of the layout                   |
 | `--rui-Grid__justify-items`                          | Default horizontal alignment of grid items                   |
 | `--rui-Grid__auto-flow`                              | Default auto-flow algorithm                                  |
+
+[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
+[aling-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

package/src/lib/components/{layout/Grid → Grid}/_theme.scss

@@ -1,10 +1,9 @@
-$auto-flow: var(--rui-Grid__auto-flow);
-
 $responsive-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),
+  auto-flow: var(--rui-Grid__auto-flow),
   align-content: var(--rui-Grid__align-content),
   align-items: var(--rui-Grid__align-items),
   justify-content: var(--rui-Grid__justify-content),

package/src/lib/components/{layout/Grid → Grid}/_tools.scss

@@ -1,6 +1,6 @@
 @use 'sass:map';
-@use '../../../styles/settings/breakpoints';
-@use '../../../styles/tools/breakpoint';
+@use '../../styles/settings/breakpoints';
+@use '../../styles/tools/breakpoint';
 
 // Generate fallback cascade using `var()` function fallbacks.
 //

package/src/lib/components/Link/Link.jsx

@@ -0,0 +1,45 @@
+import PropTypes from 'prop-types';
+import React from 'react';
+import transferProps from '../../utils/transferProps';
+import { withProviderContext } from '../../provider';
+import styles from './Link.scss';
+
+export const Link = ({
+  children,
+  href,
+  id,
+  ...restProps
+}) => (
+  <a
+    {...transferProps(restProps)}
+    href={href}
+    className={styles.root}
+    id={id}
+  >
+    {children}
+  </a>
+);
+
+Link.defaultProps = {
+  children: null,
+  id: undefined,
+};
+
+Link.propTypes = {
+  /**
+   * Content of the link.
+   */
+  children: PropTypes.node,
+  /**
+   * Link's `href` attribute.
+   */
+  href: PropTypes.string.isRequired,
+  /**
+   * ID of the root HTML element.
+   */
+  id: PropTypes.string,
+};
+
+export const LinkWithContext = withProviderContext(Link, 'Link');
+
+export default LinkWithContext;

package/src/lib/components/Link/Link.scss

@@ -0,0 +1,11 @@
+@use 'theme';
+
+.root {
+  text-decoration: theme.$link-text-decoration;
+  color: theme.$link-color;
+
+  &:hover {
+    text-decoration: theme.$link-hover-text-decoration;
+    color: theme.$link-hover-color;
+  }
+}

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

@@ -0,0 +1,85 @@
+---
+name: Link
+menu: 'Actions'
+route: /components/link
+---
+
+# Link
+
+import {
+  Playground,
+  Props,
+} from 'docz'
+import Placeholder from '../../../docs/_components/Placeholder'
+import { Link } from './Link'
+
+Link allow users to follow navigation.
+
+## Basic Usage
+
+To implement the Link component, you need to import it first:
+
+```js
+import { Link } from '@react-ui-org/react-ui';
+```
+
+And use it:
+
+<Playground>
+  <Link href="/contribute/guidelines">How can I contribute to React UI?</Link>
+</Playground>
+
+See [API](#api) for all available options.
+
+## General Guidelines
+
+**Avoid using links for actions**, use a [Button](/components/ui/button)
+instead. This is because users expect navigation to happen when clicking on
+something what looks like a link.
+
+## Block-Level Content
+
+Besides text, link can contain block-level elements too.
+
+<Playground>
+  <Link href="/contribute/guidelines">
+    <Placeholder>Block-level element wrapped with link</Placeholder>
+  </Link>
+</Playground>
+
+## Custom Routing
+
+It's common to use custom function for routing within SPAs. Use the
+`onClick` option to provide such function.
+
+<Playground>
+  <Link
+    href="/contribute/guidelines"
+    onClick={(event) => {
+      event.preventDefault();
+      window.location = event.currentTarget.getAttribute('href');
+    }}
+  >
+    This link is controlled by custom function
+  </Link>
+</Playground>
+
+## API
+
+In addition to the options below, you can specify [React synthetic events] or
+any custom HTML attributes that do not interfere with the API, and they will be
+passed to the `a` HTML element. This enables making the component interactive
+and helps improve its accessibility.
+
+<Props table of={Link} />
+
+## Theming
+
+| Custom Property                      | Description                                  |
+|--------------------------------------|----------------------------------------------|
+| `--rui-Link__color`                  | Text color                                   |
+| `--rui-Link__text-decoration`        | Text decoration, e.g. underline              |
+| `--rui-Link--hover__color`           | Text color on hover                          |
+| `--rui-Link--hover__text-decoration` | Text decoration on hover                     |
+
+[React synthetic events]: https://reactjs.org/docs/events.html

package/src/lib/components/Link/_theme.scss

@@ -0,0 +1,4 @@
+$link-color: var(--rui-Link__color);
+$link-text-decoration: var(--rui-Link__text-decoration);
+$link-hover-color: var(--rui-Link--hover__color);
+$link-hover-text-decoration: var(--rui-Link--hover__text-decoration);

package/src/lib/components/Link/index.js

@@ -0,0 +1 @@
+export { default } from './Link';

package/src/lib/components/{layout/List → List}/List.jsx

@@ -1,6 +1,6 @@
 import PropTypes from 'prop-types';
 import React from 'react';
-import { withProviderContext } from '../../../provider';
+import { withProviderContext } from '../../provider';
 import styles from './List.scss';
 
 export const List = ({

package/src/lib/components/{layout/List → List}/List.scss

@@ -1,5 +1,5 @@
-@use '../../../styles/tools/reset';
-@use '../../../styles/tools/spacing';
+@use '../../styles/tools/reset';
+@use '../../styles/tools/spacing';
 @use 'theme';
 
 .root {

package/src/lib/components/{layout/List → List}/ListItem.jsx

@@ -1,6 +1,6 @@
 import PropTypes from 'prop-types';
 import React from 'react';
-import { withProviderContext } from '../../../provider';
+import { withProviderContext } from '../../provider';
 import styles from './List.scss';
 
 export const ListItem = ({ children }) => {

package/src/lib/components/{layout/List → List}/README.mdx

@@ -1,7 +1,7 @@
 ---
 name: List
 menu: 'Layouts'
-route: /components/layout/list
+route: /components/list
 ---
 
 # List
@@ -10,7 +10,7 @@ import {
   Playground,
   Props,
 } from 'docz'
-import { Placeholder } from '../../../../docs/_components/Placeholder/Placeholder'
+import { Placeholder } from '../../../docs/_components/Placeholder/Placeholder'
 import { List } from './List'
 import { ListItem } from './ListItem'
 

package/src/lib/components/{layout/Media → Media}/Media.jsx

@@ -1,6 +1,6 @@
 import PropTypes from 'prop-types';
 import React from 'react';
-import { withProviderContext } from '../../../provider';
+import { withProviderContext } from '../../provider';
 import styles from './Media.scss';
 
 export const Media = (props) => {
@@ -17,7 +17,9 @@ export const Media = (props) => {
 
 Media.propTypes = {
   /**
-   * Slot for MediaBody and MediaObject components.
+   * Nested elements. Supported types are:
+   * * `MediaBody`
+   * * `MediaObject`
    */
   children: PropTypes.node.isRequired,
 };

package/src/lib/components/{layout/Media → Media}/Media.scss

@@ -1,4 +1,4 @@
-@use '../../../styles/tools/spacing';
+@use '../../styles/tools/spacing';
 
 .media {
   @include spacing.bottom(layouts);

package/src/lib/components/{layout/Media → Media}/MediaBody.jsx

@@ -1,6 +1,6 @@
 import PropTypes from 'prop-types';
 import React from 'react';
-import { withProviderContext } from '../../../provider';
+import { withProviderContext } from '../../provider';
 import styles from './Media.scss';
 
 export const MediaBody = ({ children }) => (

package/src/lib/components/{layout/Media → Media}/MediaObject.jsx

@@ -1,6 +1,6 @@
 import PropTypes from 'prop-types';
 import React from 'react';
-import { withProviderContext } from '../../../provider';
+import { withProviderContext } from '../../provider';
 import styles from './Media.scss';
 
 export const MediaObject = ({ children }) => (

package/src/lib/components/{layout/Media → Media}/README.mdx

@@ -1,7 +1,7 @@
 ---
 name: Media
 menu: 'Layouts'
-route: /components/layout/media
+route: /components/media
 ---
 
 # Media
@@ -10,7 +10,7 @@ import {
   Playground,
   Props,
 } from 'docz'
-import { Placeholder } from '../../../../docs/_components/Placeholder/Placeholder'
+import { Placeholder } from '../../../docs/_components/Placeholder/Placeholder'
 import { Media } from './Media'
 import { MediaBody } from './MediaBody'
 import { MediaObject } from './MediaObject'