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

package/src/components/Toolbar/README.md

@@ -0,0 +1,359 @@
+# Toolbar
+
+The responsive Toolbar layout is a versatile tool that allows spacing, grouping,
+and aligning inline items.
+
+## Basic Usage
+
+To implement the Toolbar component, you need to import it first:
+
+```js
+import { Toolbar, ToolbarItem } from '@react-ui-org/react-ui';
+```
+
+And use it:
+
+```docoff-react-preview
+<Toolbar>
+  <ToolbarItem>
+    <docoff-placeholder bordered>Toolbar item</docoff-placeholder>
+  </ToolbarItem>
+  <ToolbarItem>
+    <docoff-placeholder bordered>Toolbar item</docoff-placeholder>
+  </ToolbarItem>
+  <ToolbarItem>
+    <docoff-placeholder bordered>Toolbar item</docoff-placeholder>
+  </ToolbarItem>
+</Toolbar>
+```
+
+See [API](#api) for all available options.
+
+## General Guidelines
+
+- **Toolbar is great for flexible inline layouts.** For stacking your content
+  vertically or building two-dimensional layouts head to the [Grid][grid]
+  layout.
+
+- **Wrap your items** into the ToolbarItem component. This ensures your content
+  is properly spaced and aligned with other Toolbar elements. Do **not** try to
+  put any custom HTML or React components directly into the Toolbar layout
+  without wrapping it with the ToolbarItem first.
+
+- **Be careful with using Toolbar with long or dynamic items in narrow
+  containers.** Toolbar intentionally prevents its items from shrinking using
+  `flex: none` which may cause overflow in case of lack of horizontal space.
+  Depending on your situation, consider turning on the `nowrap` option
+  (which allows shrinking of items but disables Toolbar from wrapping), using
+  the [Text][text] component to precisely control text wrapping, or switching to
+  the [Grid][grid] layout.
+
+## Alignment
+
+You can tweak your Toolbar layout using rich alignment options, both in
+horizontal and vertical direction.
+
+👉 At the current stage of development, React UI is **RTL aware** so switching
+to a fully RTL-compatible behavior in the future should be painless. That's why
+the justification values are called rather `start` than `left` and `end` instead
+of `right`.
+
+```docoff-react-preview
+React.createElement(() => {
+  const [alignment, setAlignment] = React.useState('top');
+  const [justification, setJustification] = React.useState('start');
+  return (
+    <div>
+      <Toolbar>
+        <ToolbarGroup align="baseline">
+          <ToolbarItem>
+            <span id="alignment-label">Alignment:</span>
+          </ToolbarItem>
+          <ToolbarItem>
+            <ButtonGroup aria-labelledby="alignment-label" priority="outline">
+              <Button
+                aria-pressed={alignment === 'top'}
+                color={alignment === 'top' ? 'selected' : 'secondary'}
+                label="top"
+                onClick={() => setAlignment('top')}
+              />
+              <Button
+                aria-pressed={alignment === 'middle'}
+                color={alignment === 'middle' ? 'selected' : 'secondary'}
+                label="middle"
+                onClick={() => setAlignment('middle')}
+              />
+              <Button
+                aria-pressed={alignment === 'bottom'}
+                color={alignment === 'bottom' ? 'selected' : 'secondary'}
+                label="bottom"
+                onClick={() => setAlignment('bottom')}
+              />
+              <Button
+                aria-pressed={alignment === 'baseline'}
+                color={alignment === 'baseline' ? 'selected' : 'secondary'}
+                label="baseline"
+                onClick={() => setAlignment('baseline')}
+              />
+            </ButtonGroup>
+          </ToolbarItem>
+        </ToolbarGroup>
+        <ToolbarGroup align="baseline">
+          <ToolbarItem>
+            <span id="justification-label">Justification:</span>
+          </ToolbarItem>
+          <ToolbarItem>
+            <ButtonGroup aria-labelledby="justification-label" priority="outline">
+              <Button
+                aria-pressed={justification === 'start'}
+                color={justification === 'start' ? 'selected' : 'secondary'}
+                label="start"
+                onClick={() => setJustification('start')}
+              />
+              <Button
+                aria-pressed={justification === 'center'}
+                color={justification === 'center' ? 'selected' : 'secondary'}
+                label="center"
+                onClick={() => setJustification('center')}
+              />
+              <Button
+                aria-pressed={justification === 'end'}
+                color={justification === 'end' ? 'selected' : 'secondary'}
+                label="end"
+                onClick={() => setJustification('end')}
+              />
+              <Button
+                aria-pressed={justification === 'space-between'}
+                color={justification === 'space-between' ? 'selected' : 'secondary'}
+                label="space-between"
+                onClick={() => setJustification('space-between')}
+              />
+            </ButtonGroup>
+          </ToolbarItem>
+        </ToolbarGroup>
+      </Toolbar>
+      <Toolbar align={alignment} justify={justification}>
+        <ToolbarItem>
+          <docoff-placeholder bordered>First item</docoff-placeholder>
+        </ToolbarItem>
+        <ToolbarItem>
+          <docoff-placeholder bordered>
+            Second item<br />
+            is taller
+          </docoff-placeholder>
+        </ToolbarItem>
+        <ToolbarItem>
+          <docoff-placeholder bordered>Third item</docoff-placeholder>
+        </ToolbarItem>
+      </Toolbar>
+    </div>
+  );
+});
+```
+
+## Groups
+
+Toolbar items can be grouped which enables you aligning related items together.
+To provide the best possible flexibility for building your layout, the
+ToolbarGroup allows you to set many options similar to the Toolbar: vertical
+alignment, [dense spacing](#dense-layout), or [disable wrapping](#wrapping).
+
+```docoff-react-preview
+<Toolbar justify="space-between">
+  <ToolbarGroup>
+    <ToolbarItem>
+      <docoff-placeholder bordered>Group A</docoff-placeholder>
+    </ToolbarItem>
+    <ToolbarItem>
+      <docoff-placeholder bordered>Group A</docoff-placeholder>
+    </ToolbarItem>
+  </ToolbarGroup>
+  <ToolbarGroup align="middle">
+    <ToolbarItem>
+      <docoff-placeholder bordered>Group B</docoff-placeholder>
+    </ToolbarItem>
+    <ToolbarItem>
+      <docoff-placeholder bordered>Group B</docoff-placeholder>
+    </ToolbarItem>
+  </ToolbarGroup>
+  <ToolbarItem>
+    <docoff-placeholder bordered>Item</docoff-placeholder>
+  </ToolbarItem>
+</Toolbar>
+```
+
+## Dense Layout
+
+Sometimes it's useful to get related items even closer together. This can be
+easily achieved through the `dense` option which can be applied on individual
+toolbar groups, or on the entire toolbar.
+
+```docoff-react-preview
+React.createElement(() => {
+  const [isGroupDense, setIsGroupDense] = React.useState(false);
+  const [isToolbarDense, setIsToolbarDense] = React.useState(false);
+  return (
+    <div>
+      <Toolbar>
+        <ToolbarItem>
+          <CheckboxField
+            checked={isGroupDense}
+            label="Dense ToolbarGroup"
+            onChange={(e) => setIsGroupDense(e.target.checked)}
+          />
+        </ToolbarItem>
+        <ToolbarItem>
+          <CheckboxField
+            checked={isToolbarDense}
+            label="Dense Toolbar"
+            onChange={(e) => setIsToolbarDense(e.target.checked)}
+          />
+        </ToolbarItem>
+      </Toolbar>
+      <Toolbar dense={isToolbarDense}>
+        <ToolbarGroup dense={isGroupDense}>
+          <ToolbarItem>
+            <docoff-placeholder bordered>Group item</docoff-placeholder>
+          </ToolbarItem>
+          <ToolbarItem>
+            <docoff-placeholder bordered>Group item</docoff-placeholder>
+          </ToolbarItem>
+        </ToolbarGroup>
+        <ToolbarItem>
+          <docoff-placeholder bordered>Standalone item</docoff-placeholder>
+        </ToolbarItem>
+        <ToolbarItem>
+          <docoff-placeholder bordered>Standalone item</docoff-placeholder>
+        </ToolbarItem>
+      </Toolbar>
+    </div>
+  );
+});
+```
+
+## Wrapping
+
+By default, all toolbar items are queued up one after another in a row. The
+items automatically wrap and create a new row. To prevent this behavior, just
+set the `nowrap` option on the Toolbar or on individual ToolbarGroups. Note that
+ToolbarGroups can still wrap when the wrapping is disabled just on their parent
+Toolbar.
+
+```docoff-react-preview
+<p>Disabled wrapping on entire toolbar:</p>
+<Toolbar justify="space-between" nowrap>
+  <ToolbarGroup>
+    <ToolbarItem>
+      <docoff-placeholder bordered>Group A</docoff-placeholder>
+    </ToolbarItem>
+    <ToolbarItem>
+      <docoff-placeholder bordered>Group A</docoff-placeholder>
+    </ToolbarItem>
+  </ToolbarGroup>
+  <ToolbarGroup>
+    <ToolbarItem>
+      <docoff-placeholder bordered>Group B</docoff-placeholder>
+    </ToolbarItem>
+    <ToolbarItem>
+      <docoff-placeholder bordered>Group B</docoff-placeholder>
+    </ToolbarItem>
+  </ToolbarGroup>
+  <ToolbarItem>
+    <docoff-placeholder bordered>Item</docoff-placeholder>
+  </ToolbarItem>
+</Toolbar>
+<p>Disabled wrapping on toolbar groups:</p>
+<Toolbar justify="space-between">
+  <ToolbarGroup nowrap>
+    <ToolbarItem>
+      <docoff-placeholder bordered>Group A</docoff-placeholder>
+    </ToolbarItem>
+    <ToolbarItem>
+      <docoff-placeholder bordered>Group A</docoff-placeholder>
+    </ToolbarItem>
+  </ToolbarGroup>
+  <ToolbarGroup nowrap>
+    <ToolbarItem>
+      <docoff-placeholder bordered>Group B</docoff-placeholder>
+    </ToolbarItem>
+    <ToolbarItem>
+      <docoff-placeholder bordered>Group B</docoff-placeholder>
+    </ToolbarItem>
+  </ToolbarGroup>
+  <ToolbarItem>
+    <docoff-placeholder bordered>Item</docoff-placeholder>
+  </ToolbarItem>
+</Toolbar>
+```
+
+👉 Depending on your situation, you may need to further control wrapping of text
+content placed within Toolbar. The [Text][text] component is designed
+specifically for this kind of job.
+
+## Flexible Items
+
+Toolbar items can be made flexible to grow and shrink according to the available
+space. This is useful e.g. when you need to combine text with an action:
+
+```docoff-react-preview
+<Toolbar>
+  <ToolbarItem flexible>
+    <docoff-placeholder bordered>My Headline</docoff-placeholder>
+  </ToolbarItem>
+  <ToolbarItem>
+    <docoff-placeholder bordered>Action</docoff-placeholder>
+  </ToolbarItem>
+</Toolbar>
+```
+
+Or to build a classic media layout with image on the left and text on the right:
+
+```docoff-react-preview
+<Toolbar>
+  <ToolbarItem>
+    <docoff-placeholder bordered>Media object</docoff-placeholder>
+  </ToolbarItem>
+  <ToolbarItem flexible>
+    <docoff-placeholder bordered>Media body</docoff-placeholder>
+  </ToolbarItem>
+</Toolbar>
+```
+
+## 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 root `<div>`
+HTML element. This 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.
+
+## API
+
+<docoff-react-props src="/components/Toolbar/Toolbar.jsx"></docoff-react-props>
+
+### ToolbarGroup API
+
+A wrapper for grouping ToolbarItems together.
+
+<docoff-react-props src="/components/Toolbar/ToolbarGroup.jsx"></docoff-react-props>
+
+### ToolbarItem API
+
+A wrapper for individual toolbar items.
+
+<docoff-react-props src="/components/Toolbar/ToolbarItem.jsx"></docoff-react-props>
+
+## Theming
+
+| Custom Property                                      | Description                                                  |
+|------------------------------------------------------|--------------------------------------------------------------|
+| `--rui-Toolbar__gap`                                 | Gap between toolbar items                                    |
+| `--rui-Toolbar__gap--dense`                          | Dense gap between toolbar items                              |
+
+[grid]: /components/Grid
+[text]: /components/Text
+[React synthetic events]: https://reactjs.org/docs/events.html
+[div]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/div#attributes

package/src/{lib/components → components}/Toolbar/_helpers/getAlignClassName.js

@@ -1,19 +1,27 @@
 export const getAlignClassName = (value, styles, type) => {
   if (value === 'top') {
-    if (type === 'group') return styles.isGroupAlignedToTop;
+    if (type === 'group') {
+      return styles.isGroupAlignedToTop;
+    }
     return styles.isToolbarAlignedToTop;
   }
 
   if (value === 'middle') {
-    if (type === 'group') return styles.isGroupAlignedToMiddle;
+    if (type === 'group') {
+      return styles.isGroupAlignedToMiddle;
+    }
     return styles.isToolbarAlignedToMiddle;
   }
 
   if (value === 'bottom') {
-    if (type === 'group') return styles.isGroupAlignedToBottom;
+    if (type === 'group') {
+      return styles.isGroupAlignedToBottom;
+    }
     return styles.isToolbarAlignedToBottom;
   }
 
-  if (type === 'group') return styles.isGroupAlignedToBaseline;
+  if (type === 'group') {
+    return styles.isGroupAlignedToBaseline;
+  }
   return styles.isToolbarAlignedToBaseline;
 };

package/src/components/_helpers/getRootPriorityClassName.js

@@ -0,0 +1,15 @@
+export default (priority, styles) => {
+  if (priority === 'filled') {
+    return styles.isRootPriorityFilled;
+  }
+
+  if (priority === 'outline') {
+    return styles.isRootPriorityOutline;
+  }
+
+  if (priority === 'flat') {
+    return styles.isRootPriorityFlat;
+  }
+
+  return null;
+};

package/src/{lib/index.js → index.js}

@@ -1,3 +1,9 @@
+// Global definitions
+// These need to be imported here to be placed in the distribution CSS file
+import './theme.scss';
+import './foundation.scss';
+import './helpers.scss';
+
 // Components
 export { Alert } from './components/Alert';
 export { Badge } from './components/Badge';

package/src/{lib/provider → provider}/RUIProvider.jsx

@@ -1,5 +1,7 @@
 import PropTypes from 'prop-types';
-import React from 'react';
+import React, {
+  useMemo,
+} from 'react';
 import defaultTranslations from '../translations/en';
 import RUIContext from './RUIContext';
 
@@ -7,16 +9,20 @@ const RUIProvider = ({
   children,
   globalProps,
   translations,
-}) => (
-  <RUIContext.Provider
-    value={{
-      globalProps,
-      translations,
-    }}
-  >
-    {children}
-  </RUIContext.Provider>
-);
+}) => {
+  const childProps = useMemo(() => ({
+    globalProps,
+    translations,
+  }), [globalProps, translations]);
+
+  return (
+    <RUIContext.Provider
+      value={childProps}
+    >
+      {children}
+    </RUIContext.Provider>
+  );
+};
 
 RUIProvider.defaultProps = {
   children: null,

package/src/{lib/styles → styles}/tools/_caret.scss

@@ -6,7 +6,7 @@
     height: 0.4375rem;
     border-width: 2px;
     border-style: none solid solid none;
-    border-color: currentColor;
+    border-color: currentcolor;
 }
 
 @mixin rotate($rotate: 0) {

package/src/{lib/styles → styles}/tools/form-fields/_box-field-elements.scss

@@ -7,7 +7,7 @@
 
 @use "../../settings/form-fields" as settings;
 @use "../../theme/form-fields" as theme;
-@use "../../tools/caret";
+@use "../caret";
 @use "../spacing";
 @use "../transition";
 

package/src/{lib/styles → styles}/tools/form-fields/_inline-field-elements.scss

@@ -11,7 +11,7 @@
 
 @use "../../theme/typography";
 @use "../../theme/form-fields" as theme;
-@use "../../tools/accessibility";
+@use "../accessibility";
 @use "../transition";
 
 @mixin check-input($type) {
@@ -26,7 +26,7 @@
     background-size: contain;
     background-repeat: no-repeat;
     background-color: var(--rui-local-check-background-color);
-    color-adjust: exact; // 1.
+    print-color-adjust: exact; // 1.
 
     &:focus,
     &:checked:focus {

package/src/{lib/theme.scss → theme.scss}

@@ -4,7 +4,8 @@
 @use "styles/theme-constants/colors";
 @use "styles/theme-constants/svg";
 
-:root {
+:root,
+:host {
     // ============================================================================================ //
     // GLOBAL TOKENS                                                                                //
     // ============================================================================================ //
@@ -717,7 +718,7 @@
     // ButtonGroup: filled buttons
     --rui-ButtonGroup--filled__gap: calc(-1 * var(--rui-Button__border-width));
     --rui-ButtonGroup--filled__separator__width: var(--rui-Button__border-width);
-    --rui-ButtonGroup--filled__separator__color: currentColor;
+    --rui-ButtonGroup--filled__separator__color: currentcolor;
 
     // ButtonGroup: outline buttons
     --rui-ButtonGroup--outline__gap: calc(-1 * var(--rui-Button__border-width));
@@ -727,7 +728,7 @@
     // ButtonGroup: flat buttons
     --rui-ButtonGroup--flat__gap: var(--rui-Button__border-width);
     --rui-ButtonGroup--flat__separator__width: var(--rui-ButtonGroup--flat__gap);
-    --rui-ButtonGroup--flat__separator__color: currentColor;
+    --rui-ButtonGroup--flat__separator__color: currentcolor;
 
     //
     // Card

package/CONTRIBUTING.md

@@ -1,137 +0,0 @@
----
-name: General Guidelines
-route: /contribute/guidelines
-menu: Contribute
----
-
-# Contributing
-
-In the first place, thank you for your interest in contributing! 🙏
-
-## Development
-
-To build the project:
-
-1. Install local npm packages: `npm install`
-2. Run the build: `npm run build`
-
-To run the dev server:
-
-1. Install local npm packages: `npm install`
-2. Run the dev server (usually on `http://localhost:3000`): `npm start`
-
-## Git Workflow
-
-In order for the automation to work in the best possible way (we use GitHub
-Actions), please follow these guidelines:
-
-1. **One pull request per subject.** Don't combine unrelated changes in a single
-   PR unless they are really subtle details such as fix of a typo.
-
-2. **Only PRs into `master` branch are listed in changelog.** PRs into other
-   branches are not picked up by release automation.
-
-3. **Name your branches according to nature of change.** Choose one of:
-
-   - `bc/*` for breaking changes
-   - `feature/*` for features
-   - `bugfix/*` for bugfixes
-   - `refactoring/*` for refactoring of the library
-   - `docs/*` or `documentation/*` for changes in docs
-   - `maintenance/*` for maintenance (builds, dependencies, automation, etc.)
-   - `release/*` for [releases](/contribute/releasing) (administrators only)
-
-4. **Write clear, helpful and descriptive commit messages.**
-
-   1. **Use imperative and write in English,** e.g. _Update dependencies_ or
-      _Claim support for controlled components only_.
-   2. **If an issue exists for your changes, append the issue number** in
-      parentheses to the end of the commit message, e.g. _Update dependencies
-      (#261)_.
-   3. Optionally use Markdown code blocks to emphasize, e.g.
-      _Create `ScrollView` component (#53)_.
-
-5. **Write clear, helpful and descriptive PR names.**
-
-   1. **All rules for commit messages apply** also for PR names.
-   2. **Always check that PR name meets the requirements** above because **PR
-      names are used in changelog**. GitHub automatically truncates long PR
-      names and picks up branch name for multi-commit PRs, so it's necessary to
-      make sure the PR name is what we want to have in the changelog.
-   3. **If an issue exists for your changes, append this text to PR
-      description** (the topmost comment in the PR) in order for the issue to be
-      closed automatically once the PR is merged: `Closes #<ISSUE NUMBER>`. You
-      will know the issue is linked correctly when it appears in the _Linked
-      issues_ section of the PR. (Having the issue mentioned in commit message
-      and/or PR name does _not_ have this effect.)
-   4. **If there is no issue for your changes, please add your PR to `The
-      Board`** GitHub project in the _Projects_ section of the PR. The correct
-      board column will be selected automatically. This helps us keep track of
-      what is in development.
-
-Pull requests are labelled automatically. You can add more labels to better
-qualify the nature of the change — in such case, it will be included in all
-corresponding changelog groups. Or use the `skip changelog` label to exclude a
-pull request from the changelog.
-
-## Package Linking
-
-The best way for development of React UI is to link `react-ui` into your
-application with `npm link` so you can see it in action.
-
-1. In React UI repository, run `npm link`
-2. In your application, run `npm link @react-ui-org/react-ui`
-
-To prevent
-[Invalid Hook Call Warning](https://reactjs.org/warnings/invalid-hook-call-warning.html#duplicate-react)
-when React UI is linked, add the following code to your app's Webpack config:
-
-```js
-const path = require('path');
-
-module.exports = {
-  resolve: {
-    alias: {
-      react: path.resolve('./node_modules/react'),
-      'react-dom': path.resolve('./node_modules/react-dom'),
-    },
-  },
-};
-```
-
-## General Guidelines
-
-To keep React UI consistent and predictable the following guidelines should be observed:
-
-1. If component accepts the `children` prop it should be either required or the element
-   should return `null` when no children are provided.
-
-## Documenting
-
-We use [Docz](https://docz.site) (powered by [Gatsby](https://www.gatsbyjs.com))
-as the documentation platform. The documentation itself is written in
-[MDX](https://mdxjs.com) format — a human-readable blend of the popular Markdown
-and JSX syntax.
-
-Run `npm start` to run the docs in development mode, and open
-`http://localhost:3000` in your browser to see the docs in live-reload mode.
-
-A few things to note:
-
-- In order to get component props parsed and rendered by Docz, it's crucial to
-  **import the component into an MDX file right from its source file** — parsing
-  a re-exported component (typically via `index.js`) isn't currently supported.
-
-- If you don't want Gatsby to collect **anonymous statistics**, you may want to
-  disable [Gatsby telemetry](https://www.gatsbyjs.com/docs/telemetry/) by
-  running `npx gatsby telemetry --disable`.
-
-- If you see the Not found page after having **changed the configuration of Docz
-  or Gatsby in the live-reload mode,** you may either restart the Docz
-  development server (`ctrl + c` and `npm start`), or try to edit an MDX file
-  which makes the Docz rebuild, too.
-
-- To **make your authoring experience better,** we recommend to make sure your
-  IDE understands the MDX syntax and is able to help you wrap lines in MD and
-  MDX files automatically (Jetbrains IDE's and VSCode support both features
-  out-of-the-box or through a plugin).