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

package/src/components/Button/README.md

@@ -0,0 +1,580 @@
+# Button
+
+Buttons allow users to take actions.
+
+## Basic Usage
+
+To implement the Button component, you need to import it first:
+
+```js
+import { Button } from '@react-ui-org/react-ui';
+```
+
+And use it:
+
+```docoff-react-preview
+<Button label="My button" />
+```
+
+See [API](#api) for all available options.
+
+## General Guidelines
+
+- Use **short yet comprehensible labels** to make buttons fit small screens.
+
+- Since buttons are there to take actions, **use a verb** to make it obvious
+  what your buttons do.
+
+- **Don't overwhelm your UI** with too many high-emphasis actions. There should
+  always be one but chances are that having more of them is not necessary.
+
+## Priorities
+
+There are three **visual priorities** of buttons to choose from, from highest to
+lowest:
+
+1. filled
+2. outline
+3. flat
+
+All priorities come in supported
+[component colors](/docs/foundation/colors#component-colors).
+
+### Filled
+
+The default, high-emphasis priority should be used for primary actions of your
+app. Use it sparingly but remember there should always be one on a screen.
+
+```docoff-react-preview
+<Button label="Primary" />
+<Button label="Secondary" color="secondary" />
+<Button label="Selected" color="selected" />
+<Button label="Success" color="success" />
+<Button label="Warning" color="warning" />
+<Button label="Danger" color="danger" />
+<Button label="Help" color="help" />
+<Button label="Info" color="info" />
+<Button label="Note" color="note" />
+<docoff-placeholder dark inline>
+  <Button label="Light" color="light" />
+</docoff-placeholder>
+<Button label="Dark" color="dark" />
+```
+
+Default, unconfigured button comes in **medium** size, **filled** visual
+priority, and **primary** color variant.
+
+### Outline
+
+Medium-emphasis buttons. They are designed to contain actions that are
+important but not primary in your app.
+
+```docoff-react-preview
+<Button priority="outline" label="Primary" />
+<Button priority="outline" label="Secondary" color="secondary" />
+<Button priority="outline" label="Selected" color="selected" />
+<Button priority="outline" label="Success" color="success" />
+<Button priority="outline" label="Warning" color="warning" />
+<Button priority="outline" label="Danger" color="danger" />
+<Button priority="outline" label="Help" color="help" />
+<Button priority="outline" label="Info" color="info" />
+<Button priority="outline" label="Note" color="note" />
+<docoff-placeholder dark inline>
+  <Button priority="outline" label="Light" color="light" />
+</docoff-placeholder>
+<Button priority="outline" label="Dark" color="dark" />
+```
+
+### Flat
+
+Flat buttons are designed for less pronounced actions to help maintain focus on
+the content.
+
+```docoff-react-preview
+<Button priority="flat" label="Primary" />
+<Button priority="flat" label="Secondary" color="secondary" />
+<Button priority="flat" label="Selected" color="selected" />
+<Button priority="flat" label="Success" color="success" />
+<Button priority="flat" label="Warning" color="warning" />
+<Button priority="flat" label="Danger" color="danger" />
+<Button priority="flat" label="Help" color="help" />
+<Button priority="flat" label="Info" color="info" />
+<Button priority="flat" label="Note" color="note" />
+<docoff-placeholder dark inline>
+  <Button priority="flat" label="Light" color="light" />
+</docoff-placeholder>
+<Button priority="flat" label="Dark" color="dark" />
+```
+
+## Sizes
+
+Aside from the default (medium) size, two additional sizes are available: small
+and large.
+
+```docoff-react-preview
+<Button label="Small" size="small" />
+<Button label="Medium" />
+<Button label="Large" size="large" />
+```
+
+Block buttons span the full width of a parent:
+
+```docoff-react-preview
+<Button label="Block button" block />
+```
+
+## Buttons with Icons
+
+To improve clarity or to draw attention to the action, icons can be added
+before or after the button's label.
+
+👉 Please note there are no icons pre-packed in React UI. Visit
+[Icons](/docs/foundation/icons) to see how to include them.
+
+```docoff-react-preview
+<Button
+  label="Icon before label"
+  beforeLabel={<rui-icon icon="star" />}
+/>
+<Button
+  label="Icon after label"
+  afterLabel={<rui-icon icon="star" />}
+/>
+```
+
+### Icon Buttons
+
+For clear and simple actions, buttons can visually consist just of an icon.
+Label remains mandatory to keep the button accessible.
+
+```docoff-react-preview
+  <Button
+    label="Icon button"
+    labelVisibility="none"
+    beforeLabel={<rui-icon icon="pencil" />}
+  />
+```
+
+Icon buttons can optionally enhance on a [breakpoint](/docs/foundation/breakpoints)
+of your choice and display label once you know there is enough room for it.
+
+📐 Try resizing your browser to see how label visibility changes.
+
+```docoff-react-preview
+  <Button
+    label="Label visible from sm up"
+    labelVisibility="sm"
+    beforeLabel={<rui-icon icon="pencil" />}
+  />
+  <Button
+    label="Label visible from md up"
+    labelVisibility="md"
+    beforeLabel={<rui-icon icon="pencil" />}
+  />
+  <Button
+    label="Label visible from lg up"
+    labelVisibility="lg"
+    beforeLabel={<rui-icon icon="pencil" />}
+  />
+  <Button
+    label="Label visible from xl up"
+    labelVisibility="xl"
+    beforeLabel={<rui-icon icon="pencil" />}
+  />
+  <Button
+    label="Label visible from x2l up"
+    labelVisibility="x2l"
+    beforeLabel={<rui-icon icon="pencil" />}
+  />
+  <Button
+    label="Label visible from x3l up"
+    labelVisibility="x3l"
+    beforeLabel={<rui-icon icon="pencil" />}
+  />
+```
+
+## Buttons with Badges
+
+A [Badge](/components/Badge) can be added to buttons to provide additional
+information or to draw user's attention.
+
+```docoff-react-preview
+  <Button
+    label="Badge before"
+    beforeLabel={<Badge label={'3'} priority="outline" color="light" />}
+  />
+  <Button
+    label="Badge before, on top"
+    startCorner={<Badge label={'3'} />}
+  />
+  <Button
+    label="Badge after, on top"
+    endCorner={<Badge label={'3'} />}
+    priority="outline"
+  />
+  <Button
+    label="Badge after"
+    afterLabel={<Badge label="new" color="warning" />}
+    priority="outline"
+  />
+```
+
+### Icon Buttons with a Badge
+
+Badges play nicely with icon buttons, too:
+
+```docoff-react-preview
+<Button
+  label="Icon button with badge"
+  labelVisibility="none"
+  priority="outline"
+  beforeLabel={<rui-icon icon="warning-sign" />}
+  startCorner={<Badge label={'3'} color="warning" />}
+/>
+<Button
+  label="Icon button with badge"
+  labelVisibility="md"
+  priority="outline"
+  beforeLabel={<rui-icon icon="warning-sign" />}
+  startCorner={<Badge label={'3'} color="danger" />}
+/>
+```
+
+## States
+
+### Disabled State
+
+Disabled state makes the action unavailable.
+
+```docoff-react-preview
+<Button label="Disabled filled button" disabled />
+<Button label="Disabled outline button" priority="outline" disabled />
+<Button label="Disabled flat button" priority="flat" disabled />
+```
+
+### Feedback State
+
+When user's action triggers an asynchronous process on background, the button's
+feedback state (not to be mistaken with
+[feedback colors](/docs/foundation/colors#component-colors)) can be indicated by
+showing an icon. The icon replaces button's label while retaining original
+dimensions of the button. Buttons in feedback state are automatically disabled
+to prevent unwanted interaction.
+
+Filled buttons in feedback state:
+
+```docoff-react-preview
+<Button
+  label="Success"
+  color="success"
+  feedbackIcon={<rui-icon icon="success" />}
+/>
+<Button
+  label="Success"
+  labelVisibility="none"
+  color="success"
+  feedbackIcon={<rui-icon icon="success" />}
+  endCorner={<Badge color="danger" label={'3'} />}
+/>
+<docoff-placeholder dark inline>
+  <Button
+    label="Light"
+    color="light"
+    feedbackIcon={<rui-icon icon="success" />}
+  />
+</docoff-placeholder>
+<Button
+  label="Dark"
+  color="dark"
+  feedbackIcon={<rui-icon icon="success" />}
+/>
+<Button
+  label="Primary"
+  feedbackIcon={(
+    <span className="d-inline-flex animation-spin-counterclockwise">
+      <rui-icon icon="loading" />
+    </span>
+  )}
+/>
+```
+
+Outline buttons in feedback state:
+
+```docoff-react-preview
+<Button
+  label="Success"
+  priority="outline"
+  color="success"
+  feedbackIcon={<rui-icon icon="success" />}
+/>
+<Button
+  label="Success"
+  labelVisibility="none"
+  priority="outline"
+  color="success"
+  feedbackIcon={<rui-icon icon="success" />}
+  endCorner={<Badge color="danger" label={'3'} />}
+/>
+<docoff-placeholder dark inline>
+  <Button
+    label="Light"
+    priority="outline"
+    color="light"
+    feedbackIcon={<rui-icon icon="success" />}
+  />
+</docoff-placeholder>
+<Button
+  label="Dark"
+  priority="outline"
+  color="dark"
+  feedbackIcon={<rui-icon icon="success" />}
+/>
+<Button
+  label="Primary"
+  priority="outline"
+  feedbackIcon={(
+    <span className="d-inline-flex animation-spin-counterclockwise">
+      <rui-icon icon="loading" />
+    </span>
+  )}
+/>
+```
+
+Flat buttons in feedback state:
+
+```docoff-react-preview
+<Button
+  label="Success"
+  priority="flat"
+  color="success"
+  feedbackIcon={<rui-icon icon="success" />}
+/>
+<Button
+  label="Success"
+  labelVisibility="none"
+  priority="flat"
+  color="success"
+  feedbackIcon={<rui-icon icon="success" />}
+  endCorner={<Badge color="danger" label={'3'} />}
+/>
+<docoff-placeholder dark inline>
+  <Button
+    label="Light"
+    priority="flat"
+    color="light"
+    feedbackIcon={<rui-icon icon="success" />}
+  />
+</docoff-placeholder>
+<Button
+  label="Dark"
+  priority="flat"
+  color="dark"
+  feedbackIcon={<rui-icon icon="success" />}
+/>
+<Button
+  label="Primary"
+  priority="flat"
+  feedbackIcon={(
+    <span className="d-inline-flex animation-spin-counterclockwise">
+      <rui-icon icon="loading" />
+    </span>
+  )}
+/>
+```
+
+👉 Visit the [CSS Helpers](/docs/css-helpers/animation) section to see how the icon
+animation is made.
+
+## 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 native HTML
+`<button>`. 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
+[button] element.
+
+## Forwarding ref
+
+If you provide [ref], it is forwarded to the native HTML `<button>` element.
+
+## API
+
+<docoff-react-props src="/components/Button/Button.jsx"></docoff-react-props>
+
+## Theming
+
+### Common Theming Options
+
+| Custom Property                | Description                                  |
+|--------------------------------|----------------------------------------------|
+| `--rui-Button__font-weight`    | Font weight                                  |
+| `--rui-Button__text-transform` | Text transform, e.g. uppercase or small-caps |
+| `--rui-Button__letter-spacing` | Spacing between letters                      |
+| `--rui-Button__border-width`   | Border width                                 |
+| `--rui-Button__border-radius`  | Corner radius                                |
+
+### Theming Priorities and Color Variants
+
+It's possible to adjust the theme for specific priority, color variant, and
+state. Naming convention looks as follows:
+
+`--rui-Button--<PRIORITY>--<COLOR>--<INTERACTION STATE>__<PROPERTY>`
+
+Where:
+
+- `<PRIORITY>` is one of `filled`, `outline`, or `flat` (see
+  [Priorities](#priorities) and [API](#api)),
+- `<COLOR>` is one of supported
+  [component colors](/docs/foundation/colors#component-colors)
+  (see color variants of [each priority](#priorities) and [API](#api)),
+- `<INTERACTION STATE>` is one of `default`, `hover`, `active`, or `disabled`
+  (the last one being optional),
+- `<PROPERTY>` is one of:
+    - `color`, `border-color`, `background`, or `box-shadow` for the `filled`
+      priority,
+    - `color`, `border-color`, or `background` for the `outline` priority,
+    - `color` or `background` for the `flat` priority.
+
+### Theming Sizes
+
+Available sizes can be adjusted as follows:
+
+`--rui-Button--<SIZE>__<PROPERTY>`
+
+Where:
+
+- `<SIZE>` is one of `small`, `medium`, or `large` (see [Sizes](#sizes) and
+  [API](#api))
+- `<PROPERTY>` is one of `height`, `padding-x`, `padding-y`, or `font-size`
+
+👉 Button sizes are linked to
+[box field sizes](/docs/customize/theming/forms#box-field-sizes) sizes so they align
+nicely when placed in row.
+
+### Example Theme
+
+```docoff-react-preview
+<style type="text/css">
+  {`
+  .example {
+    margin: 0;
+  }
+
+  .example > * {
+    margin: 4px;
+  }
+
+  .example--themed-buttons {
+    --rui-Button__font-weight: bold;
+    --rui-Button__letter-spacing: 0.05em;
+    --rui-Button__text-transform: uppercase;
+    --rui-Button__border-radius: 0;
+    --rui-Button--filled--primary--default__box-shadow:
+      0.1em 0.1em 0.5em rgba(0, 0, 0, 0.3);
+    --rui-Button--medium__height: 3rem;
+    --rui-Button--medium__padding-x: 1.25rem;
+    --rui-Button--medium__padding-y: 0.25rem;
+  }
+  `}
+</style>
+<Button label="Default filled button" />
+<Button label="Default outline button" priority="outline" />
+<div className="example example--themed-buttons">
+  <Button label="Themed filled button" />
+  <Button label="Themed outline button" priority="outline" />
+</div>
+```
+
+### Theming Disabled State
+
+The `disabled` state offers a bit more of design flexibility compared to other
+interaction states. Firstly, there are a few common options for this state:
+
+| Custom Property                   | Description                                 |
+|-----------------------------------|---------------------------------------------|
+| `--rui-Button--disabled__opacity` | Opacity of disabled buttons                 |
+| `--rui-Button--disabled__cursor`  | Cursor to show on hovering disabled buttons |
+
+Secondly, it can be further adjusted using priority and color variant specific
+options for the disabled state:
+
+`--rui-Button--<PRIORITY>--<COLOR>--disabled__<PROPERTY>`
+
+Undefined theming options are inherited from the `default` interaction state.
+
+Example:
+
+```docoff-react-preview
+<style type="text/css">
+  {`
+  .example {
+    margin: 0;
+  }
+
+  .example > * {
+    margin: 4px;
+  }
+
+  .example--themed-disabled-buttons {
+    --rui-Button__border-radius: 0;
+    --rui-Button--disabled__opacity: 0.4;
+    --rui-Button--disabled__cursor: default;
+    --rui-Button--filled--primary--disabled__color: slate;
+    --rui-Button--filled--primary--disabled__border-color: silver;
+    --rui-Button--filled--primary--disabled__background: silver;
+    --rui-Button--filled--success--disabled__color: slate;
+    --rui-Button--filled--success--disabled__border-color: silver;
+    --rui-Button--filled--success--disabled__background: silver;
+    --rui-Button--outline--primary--disabled__color: slate;
+    --rui-Button--outline--primary--disabled__border-color: silver;
+  }
+  `}
+</style>
+<Button
+  label="Default filled primary button, disabled"
+  disabled
+/>
+<Button
+  label="Default filled success button, disabled"
+  color="success"
+  disabled
+/>
+<Button
+  label="Default outline primary button, disabled"
+  priority="outline"
+  disabled
+/>
+<div className="example example--themed-disabled-buttons">
+  <Button
+    label="Themed filled primary button, disabled"
+    disabled
+  />
+  <Button
+    label="Themed filled success button, disabled"
+    color="success"
+    disabled
+  />
+  <Button
+    label="Themed outline primary button, disabled"
+    priority="outline"
+    disabled
+  />
+</div>
+```
+
+### Theming Feedback State
+
+Similarly to disabled state, opacity and cursor can be set for buttons in
+feedback state.
+
+| Custom Property                   | Description                                          |
+|-----------------------------------|------------------------------------------------------|
+| `--rui-Button--feedback__opacity` | Opacity of buttons in feedback state                 |
+| `--rui-Button--feedback__cursor`  | Cursor to show on hovering buttons in feedback state |
+
+[React synthetic events]: https://reactjs.org/docs/events.html
+[button]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#attributes
+[ref]: https://reactjs.org/docs/refs-and-the-dom.html

package/src/{lib/components → components}/ButtonGroup/ButtonGroup.jsx

@@ -1,5 +1,7 @@
 import PropTypes from 'prop-types';
-import React from 'react';
+import React, {
+  useMemo,
+} from 'react';
 import { withGlobalProps } from '../../provider';
 import { classNames } from '../../utils/classNames';
 import getRootPriorityClassName from '../_helpers/getRootPriorityClassName';
@@ -16,6 +18,13 @@ export const ButtonGroup = ({
   size,
   ...restProps
 }) => {
+  const childProps = useMemo(() => ({
+    block,
+    disabled,
+    priority,
+    size,
+  }), [block, disabled, priority, size]);
+
   if (isChildrenEmpty(children)) {
     return null;
   }
@@ -30,14 +39,7 @@ export const ButtonGroup = ({
       )}
       disabled={disabled}
     >
-      <ButtonGroupContext.Provider
-        value={{
-          block,
-          disabled,
-          priority,
-          size,
-        }}
-      >
+      <ButtonGroupContext.Provider value={childProps}>
         {children}
       </ButtonGroupContext.Provider>
     </fieldset>