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

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

@@ -1,581 +0,0 @@
----
-name: Button
-menu: 'Actions'
-route: /components/button
----
-
-# Button
-
-import {
-  Playground,
-  Props,
-} from 'docz'
-import Icon from '../../../docs/_components/Icon'
-import Placeholder from '../../../docs/_components/Placeholder'
-import {
-  Badge,
-  Button,
-} from '../..'
-
-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:
-
-<Playground>
-  <Button label="My button" />
-</Playground>
-
-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](/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.
-
-<Playground>
-  <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" />
-  <Placeholder dark inline>
-    <Button label="Light" color="light" />
-  </Placeholder>
-  <Button label="Dark" color="dark" />
-</Playground>
-
-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.
-
-<Playground>
-  <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" />
-  <Placeholder dark inline>
-    <Button priority="outline" label="Light" color="light" />
-  </Placeholder>
-  <Button priority="outline" label="Dark" color="dark" />
-</Playground>
-
-### Flat
-
-Flat buttons are designed for less pronounced actions to help maintain focus on
-the content.
-
-<Playground>
-  <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" />
-  <Placeholder dark inline>
-    <Button priority="flat" label="Light" color="light" />
-  </Placeholder>
-  <Button priority="flat" label="Dark" color="dark" />
-</Playground>
-
-## Sizes
-
-Aside from the default (medium) size, two additional sizes are available: small
-and large.
-
-<Playground>
-  <Button label="Small" size="small" />
-  <Button label="Medium" />
-  <Button label="Large" size="large" />
-</Playground>
-
-Block buttons span the full width of a parent:
-
-<Playground>
-  <Button label="Block button" block />
-</Playground>
-
-## 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](/foundation/icons) to see how to include them.
-
-<Playground>
-  <Button
-    label="Icon before label"
-    beforeLabel={<Icon icon="star" />}
-  />
-  <Button
-    label="Icon after label"
-    afterLabel={<Icon icon="star" />}
-  />
-</Playground>
-
-### Icon Buttons
-
-For clear and simple actions, buttons can visually consist just of an icon.
-Label remains mandatory to keep the button accessible.
-
-<Playground>
-  <Button
-    label="Icon button"
-    labelVisibility="none"
-    beforeLabel={<Icon icon="pencil" />}
-  />
-</Playground>
-
-Icon buttons can optionally enhance on a [breakpoint](/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.
-
-<Playground>
-  <Button
-    label="Label visible from sm up"
-    labelVisibility="sm"
-    beforeLabel={<Icon icon="pencil" />}
-  />
-  <Button
-    label="Label visible from md up"
-    labelVisibility="md"
-    beforeLabel={<Icon icon="pencil" />}
-  />
-  <Button
-    label="Label visible from lg up"
-    labelVisibility="lg"
-    beforeLabel={<Icon icon="pencil" />}
-  />
-  <Button
-    label="Label visible from xl up"
-    labelVisibility="xl"
-    beforeLabel={<Icon icon="pencil" />}
-  />
-  <Button
-    label="Label visible from x2l up"
-    labelVisibility="x2l"
-    beforeLabel={<Icon icon="pencil" />}
-  />
-  <Button
-    label="Label visible from x3l up"
-    labelVisibility="x3l"
-    beforeLabel={<Icon icon="pencil" />}
-  />
-</Playground>
-
-## Buttons with Badges
-
-A [Badge](/components/badge) can be added to buttons to provide additional
-information or to draw user's attention.
-
-<Playground>
-  <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"
-  />
-</Playground>
-
-### Icon Buttons with a Badge
-
-Badges play nicely with icon buttons, too:
-
-<Playground>
-  <Button
-    label="Icon button with badge"
-    labelVisibility="none"
-    priority="outline"
-    beforeLabel={<Icon icon="warning-sign" />}
-    startCorner={<Badge label={3} color="warning" />}
-  />
-  <Button
-    label="Icon button with badge"
-    labelVisibility="md"
-    priority="outline"
-    beforeLabel={<Icon icon="warning-sign" />}
-    startCorner={<Badge label={3} color="danger" />}
-  />
-</Playground>
-
-## States
-
-### Disabled State
-
-Disabled state makes the action unavailable.
-
-<Playground>
-  <Button label="Disabled filled button" disabled />
-  <Button label="Disabled outline button" priority="outline" disabled />
-  <Button label="Disabled flat button" priority="flat" disabled />
-</Playground>
-
-### Feedback State
-
-When user's action triggers an asynchronous process on background, the button's
-feedback state (not to be mistaken with
-[feedback colors](/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:
-
-<Playground>
-  <Button
-    label="Success"
-    color="success"
-    feedbackIcon={<Icon icon="success" />}
-  />
-  <Button
-    label="Success"
-    labelVisibility="none"
-    color="success"
-    feedbackIcon={<Icon icon="success" />}
-    endCorner={<Badge color="danger" label={3} />}
-  />
-  <Placeholder dark inline>
-    <Button
-      label="Light"
-      color="light"
-      feedbackIcon={<Icon icon="success" />}
-    />
-  </Placeholder>
-  <Button
-    label="Dark"
-    color="dark"
-    feedbackIcon={<Icon icon="success" />}
-  />
-  <Button
-    label="Primary"
-    feedbackIcon={(
-      <span className="d-inline-flex animation-spin-counterclockwise">
-        <Icon icon="loading" />
-      </span>
-    )}
-  />
-</Playground>
-
-Outline buttons in feedback state:
-
-<Playground>
-  <Button
-    label="Success"
-    priority="outline"
-    color="success"
-    feedbackIcon={<Icon icon="success" />}
-  />
-  <Button
-    label="Success"
-    labelVisibility="none"
-    priority="outline"
-    color="success"
-    feedbackIcon={<Icon icon="success" />}
-    endCorner={<Badge color="danger" label={3} />}
-  />
-  <Placeholder dark inline>
-    <Button
-      label="Light"
-      priority="outline"
-      color="light"
-      feedbackIcon={<Icon icon="success" />}
-    />
-  </Placeholder>
-  <Button
-    label="Dark"
-    priority="outline"
-    color="dark"
-    feedbackIcon={<Icon icon="success" />}
-  />
-  <Button
-    label="Primary"
-    priority="outline"
-    feedbackIcon={(
-      <span className="d-inline-flex animation-spin-counterclockwise">
-        <Icon icon="loading" />
-      </span>
-    )}
-  />
-</Playground>
-
-Flat buttons in feedback state:
-
-<Playground>
-  <Button
-    label="Success"
-    priority="flat"
-    color="success"
-    feedbackIcon={<Icon icon="success" />}
-  />
-  <Button
-    label="Success"
-    labelVisibility="none"
-    priority="flat"
-    color="success"
-    feedbackIcon={<Icon icon="success" />}
-    endCorner={<Badge color="danger" label={3} />}
-  />
-  <Placeholder dark inline>
-    <Button
-      label="Light"
-      priority="flat"
-      color="light"
-      feedbackIcon={<Icon icon="success" />}
-    />
-  </Placeholder>
-  <Button
-    label="Dark"
-    priority="flat"
-    color="dark"
-    feedbackIcon={<Icon icon="success" />}
-  />
-  <Button
-    label="Primary"
-    priority="flat"
-    feedbackIcon={(
-      <span className="d-inline-flex animation-spin-counterclockwise">
-        <Icon icon="loading" />
-      </span>
-    )}
-  />
-</Playground>
-
-👉 Visit the [CSS Helpers](/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
-
-<Props table of={Button} />
-
-## 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](/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](/customize/theming/forms#box-field-sizes) sizes so they align
-nicely when placed in row.
-
-### Example Theme
-
-<Playground>
-  <style type="text/css">
-    {`
-      .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>
-</Playground>
-
-### 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:
-
-<Playground>
-  <style type="text/css">
-    {`
-      .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>
-</Playground>
-
-### 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