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

package/src/{lib/components/ButtonGroup/README.mdx → components/ButtonGroup/README.md}

@@ -1,23 +1,7 @@
----
-name: ButtonGroup
-menu: 'Layouts'
-route: /components/button-group
----
-
 # ButtonGroup
 
 ButtonGroup visually groups related buttons together.
 
-import {
-  Playground,
-  Props,
-} from 'docz'
-import Icon from '../../../docs/_components/Icon'
-import {
-  Button,
-  ButtonGroup,
-} from '../..'
-
 ## Basic Usage
 
 To implement the ButtonGroup component, you need to import it first:
@@ -28,13 +12,13 @@ import { ButtonGroup } from '@react-ui-org/react-ui';
 
 And use it:
 
-<Playground>
-  <ButtonGroup>
-    <Button label="Week" />
-    <Button label="Month" />
-    <Button label="Year" />
-  </ButtonGroup>
-</Playground>
+```docoff-react-preview
+<ButtonGroup>
+  <Button label="Week" />
+  <Button label="Month" />
+  <Button label="Year" />
+</ButtonGroup>
+```
 
 See [API](#api) for all available options.
 
@@ -53,11 +37,11 @@ See [API](#api) for all available options.
 - Use **short labels or icons** so the buttons can fit small screens.
 
 - For toggling between on/off states, use rather the
-  [Toggle](/components/toggle) component.
+  [Toggle](/components/Toggle) component.
 
 - For switching between options in a form that needs to be submitted, use rather
-  the [SelectField](/components/select-field) or
-  [Radio](/components/radio) components.
+  the [SelectField](/components/SelectField) or
+  [Radio](/components/Radio) components.
 
 - In the background, ButtonGroup uses the [`fieldset`][fieldset] element. Not
   only it improves the [accessibility] of the group, it also allows you to make
@@ -85,7 +69,7 @@ buttons of totally different types or sizes.
 ## Priorities
 
 There are three **visual priorities** of buttons which exactly copy the
-priorities of the [Button](/components/button) component:
+priorities of the [Button](/components/Button/) component:
 
 1. filled
 2. outline
@@ -99,72 +83,72 @@ priorities of the [Button](/components/button) component:
 The default, high-emphasis priority should be used for primary actions of your
 app.
 
-<Playground>
-  <ButtonGroup>
-    <Button color="secondary" label="Week" />
-    <Button color="secondary" label="Month" />
-    <Button color="secondary" label="Year" />
-  </ButtonGroup>
-</Playground>
+```docoff-react-preview
+<ButtonGroup>
+  <Button color="secondary" label="Week" />
+  <Button color="secondary" label="Month" />
+  <Button color="secondary" label="Year" />
+</ButtonGroup>
+```
 
 ### Outline
 
 Medium-emphasis buttons to contain actions that are important but not primary
 in your app.
 
-<Playground>
-  <ButtonGroup priority="outline">
-    <Button color="secondary" label="Week" />
-    <Button color="secondary" label="Month" />
-    <Button color="secondary" label="Year" />
-  </ButtonGroup>
-</Playground>
+```docoff-react-preview
+<ButtonGroup priority="outline">
+  <Button color="secondary" label="Week" />
+  <Button color="secondary" label="Month" />
+  <Button color="secondary" label="Year" />
+</ButtonGroup>
+```
 
 ### Flat
 
 Flat buttons are designed for less pronounced actions to help maintain focus on
 the content.
 
-<Playground>
-  <ButtonGroup priority="flat">
-    <Button color="secondary" label="Week" />
-    <Button color="secondary" label="Month" />
-    <Button color="secondary" label="Year" />
-  </ButtonGroup>
-</Playground>
+```docoff-react-preview
+<ButtonGroup priority="flat">
+  <Button color="secondary" label="Week" />
+  <Button color="secondary" label="Month" />
+  <Button color="secondary" label="Year" />
+</ButtonGroup>
+```
 
 ## Sizes
 
 All existing button sizes are also available on the button group level: small,
 medium, and large.
 
-<Playground>
-  <ButtonGroup size="small">
-    <Button color="secondary" label="Week" />
-    <Button color="secondary" label="Month" />
-    <Button color="secondary" label="Year" />
-  </ButtonGroup>
-  <ButtonGroup>
-    <Button color="secondary" label="Week" />
-    <Button color="secondary" label="Month" />
-    <Button color="secondary" label="Year" />
-  </ButtonGroup>
-  <ButtonGroup size="large">
-    <Button color="secondary" label="Week" />
-    <Button color="secondary" label="Month" />
-    <Button color="secondary" label="Year" />
-  </ButtonGroup>
-</Playground>
+```docoff-react-preview
+<ButtonGroup size="small">
+  <Button color="secondary" label="Week" />
+  <Button color="secondary" label="Month" />
+  <Button color="secondary" label="Year" />
+</ButtonGroup>
+<ButtonGroup>
+  <Button color="secondary" label="Week" />
+  <Button color="secondary" label="Month" />
+  <Button color="secondary" label="Year" />
+</ButtonGroup>
+<ButtonGroup size="large">
+  <Button color="secondary" label="Week" />
+  <Button color="secondary" label="Month" />
+  <Button color="secondary" label="Year" />
+</ButtonGroup>
+```
 
 Block button groups span the full width of a parent:
 
-<Playground>
-  <ButtonGroup block>
-    <Button color="secondary" label="Week" />
-    <Button color="secondary" label="Month" />
-    <Button color="secondary" label="Year" />
-  </ButtonGroup>
-</Playground>
+```docoff-react-preview
+<ButtonGroup block>
+  <Button color="secondary" label="Week" />
+  <Button color="secondary" label="Month" />
+  <Button color="secondary" label="Year" />
+</ButtonGroup>
+```
 
 ## States
 
@@ -172,85 +156,95 @@ Block button groups span the full width of a parent:
 
 Disables all buttons inside the group.
 
-<Playground>
-  <ButtonGroup disabled>
-    <Button color="secondary" label="Week" />
-    <Button color="secondary" label="Month" />
-    <Button color="secondary" label="Year" />
-  </ButtonGroup>
-  <ButtonGroup priority="outline" disabled>
-    <Button color="secondary" label="Week" />
-    <Button color="secondary" label="Month" />
-    <Button color="secondary" label="Year" />
-  </ButtonGroup>
-  <ButtonGroup priority="flat" disabled>
-    <Button color="secondary" label="Week" />
-    <Button color="secondary" label="Month" />
-    <Button color="secondary" label="Year" />
-  </ButtonGroup>
-</Playground>
+```docoff-react-preview
+<ButtonGroup disabled>
+  <Button color="secondary" label="Week" />
+  <Button color="secondary" label="Month" />
+  <Button color="secondary" label="Year" />
+</ButtonGroup>
+<ButtonGroup priority="outline" disabled>
+  <Button color="secondary" label="Week" />
+  <Button color="secondary" label="Month" />
+  <Button color="secondary" label="Year" />
+</ButtonGroup>
+<ButtonGroup priority="flat" disabled>
+  <Button color="secondary" label="Week" />
+  <Button color="secondary" label="Month" />
+  <Button color="secondary" label="Year" />
+</ButtonGroup>
+```
 
 ### Feedback State
 
 When user's action triggers an asynchronous process on background, feedback
 state of individual buttons can be indicated by showing an icon.
 
-<Playground>
-  <ButtonGroup>
-    <Button color="success" label="Week" feedbackIcon={<Icon icon="success" />} />
-    <Button color="secondary" label="Month" />
-    <Button color="secondary" label="Year" />
-  </ButtonGroup>
-  <ButtonGroup priority="outline">
-    <Button color="success" label="Week" feedbackIcon={<Icon icon="success" />} />
-    <Button color="secondary" label="Month" />
-    <Button color="secondary" label="Year" />
-  </ButtonGroup>
-  <ButtonGroup priority="flat">
-    <Button color="success" label="Week" feedbackIcon={<Icon icon="success" />} />
-    <Button color="secondary" label="Month" />
-    <Button color="secondary" label="Year" />
-  </ButtonGroup>
-</Playground>
+```docoff-react-preview
+<ButtonGroup>
+  <Button
+    color="success"
+    label="Week"
+    feedbackIcon={<rui-icon icon="success" />}
+  />
+  <Button color="secondary"label="Month" />
+  <Button color="secondary"label="Year" />
+</ButtonGroup>
+<ButtonGroup priority="outline">
+  <Button
+    color="success"
+    label="Week"
+    feedbackIcon={<rui-icon icon="success" />}
+  />
+  <Button color="secondary"label="Month" />
+  <Button color="secondary"label="Year" />
+</ButtonGroup>
+<ButtonGroup priority="flat">
+  <Button
+    color="success"
+    label="Week"
+    feedbackIcon={<rui-icon icon="success" />}
+  />
+  <Button color="secondary"label="Month" />
+  <Button color="secondary"label="Year" />
+</ButtonGroup>
+```
 
 ### Selected State
 
 To highlight the selected option, just apply the selected color variant for
 the desired item.
 
-<Playground>
-  <ButtonGroup>
-    <Button color="selected" label="Week" />
-    <Button color="secondary" label="Month" />
-    <Button color="secondary" label="Year" />
-  </ButtonGroup>
-  <ButtonGroup priority="outline">
-    <Button color="selected" label="Week" />
-    <Button color="secondary" label="Month" />
-    <Button color="secondary" label="Year" />
-  </ButtonGroup>
-  <ButtonGroup priority="flat">
-    <Button color="selected" label="Week" />
-    <Button color="secondary" label="Month" />
-    <Button color="secondary" label="Year" />
-  </ButtonGroup>
-</Playground>
+```docoff-react-preview
+<ButtonGroup>
+  <Button color="selected" label="Week" />
+  <Button color="secondary" label="Month" />
+  <Button color="secondary" label="Year" />
+</ButtonGroup>
+<ButtonGroup priority="outline">
+  <Button color="selected" label="Week" />
+  <Button color="secondary" label="Month" />
+  <Button color="secondary" label="Year" />
+</ButtonGroup>
+<ButtonGroup priority="flat">
+  <Button color="selected" label="Week" />
+  <Button color="secondary" label="Month" />
+  <Button color="secondary" label="Year" />
+</ButtonGroup>
+```
 
 ## Accessibility
 
 You can improve the accessibility of your ButtonGroup by linking it to a label
 and communicating the state of individual options.
 
-<Playground>
-  <>
-    <span id="period-label">Period:</span>
-    <ButtonGroup aria-labelledby="period-label">
-      <Button color="selected" label="Week" aria-pressed />
-      <Button color="secondary" label="Month" aria-pressed={false} />
-      <Button color="secondary" label="Year" aria-pressed={false} />
-    </ButtonGroup>
-  </>
-</Playground>
+```docoff-react-preview
+<span id="period-label">Period:</span>
+<ButtonGroup aria-labelledby="period-label">
+  <Button color="selected" label="Week" aria-pressed />
+  <Button color="secondary" label="Month" aria-pressed={false} />
+  <Button color="secondary" label="Year" aria-pressed={false} />
+</ButtonGroup>
+```
 
 ## Forwarding HTML Attributes
 
@@ -265,7 +259,7 @@ its accessibility.
 
 ## API
 
-<Props table of={ButtonGroup} />
+<docoff-react-props src="/components/ButtonGroup/ButtonGroup.jsx"></docoff-react-props>
 
 ## Theming
 

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

@@ -44,7 +44,7 @@ Card.propTypes = {
    */
   children: PropTypes.node.isRequired,
   /**
-   * [Color variant](/foundation/colors#component-colors) to clarify importance and meaning of the card.
+   * [Color variant](/docs/foundation/colors#component-colors) to clarify importance and meaning of the card.
    */
   color: PropTypes.oneOf(['success', 'warning', 'danger', 'help', 'info', 'note', 'light', 'dark']),
   /**

package/src/components/Card/README.md

@@ -0,0 +1,314 @@
+# Card
+
+Cards contain content and actions about a single subject.
+
+## Basic Usage
+
+To implement the Card component, you need to import at least Card and
+[CardBody](#cardbody) components:
+
+```js
+import { Card, CardBody } from '@react-ui-org/react-ui';
+```
+
+And use it:
+
+```docoff-react-preview
+<Card>
+  <CardBody>
+    Hello!
+  </CardBody>
+</Card>
+```
+
+See [API](#api) for all available options.
+
+## General Guidelines
+
+- Default card is **designed for non-white background.** You may want to either
+  use the [raised variant](#raised-card) or
+  [customize](/docs/customize/theming/overview) the default appearance to make the
+  card stand out on white surfaces.
+
+- Use optional [CardBody](#cardbody) and [CardFooter](#cardfooter) components to
+  provide your content with expected spacing.
+
+- Use **medium or low-emphasis buttons** when there are more cards, e.g. in a
+  grid. It will help you keep the UI clean and easy to scan.
+
+- **Card, or Paper?** Card is a versatile surface for displaying content.
+  However, there is also the [Paper](/components/Paper) component. While Card
+  is designed for displaying items (and also supports more visual options),
+  Paper is usually used to hold larger content areas like lists, grids, or
+  forms.
+
+## Composition
+
+Card is decomposed into the following components:
+
+- [Card](#api)
+    - [CardBody](#cardbody)
+    - [CardFooter](#cardfooter)
+
+Aside from the [CardBody](#cardbody) element, you can add a
+[CardFooter](#cardfooter) to better separate your card's actions from the rest
+of the content.
+
+Import all necessary components:
+
+```js
+import { Card, CardBody, CardFooter } from '@react-ui-org/react-ui';
+```
+
+And use them:
+
+```docoff-react-preview
+<Card>
+  <CardBody>
+    Hello! I&apos;m card with footer.
+  </CardBody>
+  <CardFooter>
+    <Button label="Read more" priority="outline" />
+  </CardFooter>
+</Card>
+```
+
+👉 CardFooter is required in case you need to align the actions of multiple
+cards with varying height of content.
+
+## Raised Card
+
+Add optional shadow to lift the card above surface.
+
+```docoff-react-preview
+<Card raised>
+  <CardBody>
+    Hello! I&apos;m raised card with footer.
+  </CardBody>
+  <CardFooter>
+    <Button label="Read more" priority="outline" />
+  </CardFooter>
+</Card>
+```
+
+## Dense Card
+
+Use a dense card when you need to save space on screen. Other elements in the
+card should be also smaller to keep the card contained and easy to scan.
+
+```docoff-react-preview
+<Card dense raised>
+  <CardBody>
+    <small>Hello! I&apos;m dense card. Everything is smaller here.</small>
+  </CardBody>
+  <CardFooter>
+    <Button label="Read more" priority="outline" size="small" />
+  </CardFooter>
+</Card>
+```
+
+## Scrollable Card
+
+Combine Card with [ScrollView](/components/ScrollView) to enable scrolling
+for card content.
+
+```docoff-react-preview
+<div
+  style={{
+    display: 'flex',
+    height: '200px',
+  }}
+>
+  <Card raised>
+    <ScrollView>
+      <CardBody>
+        Hello! I&apos;m scrollable card.
+        Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aenean commodo
+        ligula eget dolor. Aenean massa. Cum sociis natoque penatibus et magnis
+        dis parturient montes, nascetur ridiculus mus. Donec quam felis,
+        ultricies nec, pellentesque eu, pretium quis, sem. Nulla consequat massa
+        quis enim. Donec pede justo, fringilla vel, aliquet nec, vulputate eget,
+        arcu. In enim justo, rhoncus ut, imperdiet a, venenatis vitae, justo.
+        Nullam dictum felis eu pede mollis pretium. Integer tincidunt. Cras
+        dapibus. Vivamus elementum semper nisi. Aenean vulputate eleifend
+        tellus. Aenean leo ligula, porttitor eu, consequat vitae, eleifend ac,
+        enim. Aliquam lorem ante, dapibus in, viverra quis, feugiat a, tellus.
+        Phasellus viverra nulla ut metus varius laoreet. Quisque rutrum. Aenean
+        imperdiet. Etiam ultricies nisi vel augue. Curabitur ullamcorper
+        ultricies nisi. Nam eget dui. Etiam rhoncus. Maecenas tempus, tellus
+        eget condimentum rhoncus, sem quam semper libero, sit amet adipiscing
+        sem neque sed ipsum. Nam quam nunc, blandit vel, luctus pulvinar,
+        hendrerit id, lorem. Maecenas nec odio et ante tincidunt tempus.
+      </CardBody>
+    </ScrollView>
+  </Card>
+</div>
+```
+
+## Color Variants
+
+Card supports all
+[component colors](/docs/foundation/colors#component-colors) to cover different needs
+of your app.
+
+```docoff-react-preview
+<Card color="success">
+  <CardBody>
+    Hello! I&apos;m success variant of card.
+  </CardBody>
+  <CardFooter>
+    <Button label="Read more" priority="outline" color="success" />
+  </CardFooter>
+</Card>
+<Card color="warning">
+  <CardBody>
+    Hello! I&apos;m warning variant of card.
+  </CardBody>
+  <CardFooter>
+    <Button label="Read more" priority="outline" color="warning" />
+  </CardFooter>
+</Card>
+<Card color="danger">
+  <CardBody>
+    Hello! I&apos;m danger variant of card.
+  </CardBody>
+  <CardFooter>
+    <Button label="Read more" priority="outline" color="danger" />
+  </CardFooter>
+</Card>
+<Card color="help">
+  <CardBody>
+    Hello! I&apos;m help variant of card.
+  </CardBody>
+  <CardFooter>
+    <Button label="Read more" priority="outline" color="help" />
+  </CardFooter>
+</Card>
+<Card color="info">
+  <CardBody>
+    Hello! I&apos;m info variant of card.
+  </CardBody>
+  <CardFooter>
+    <Button label="Read more" priority="outline" color="info" />
+  </CardFooter>
+</Card>
+<Card color="note">
+  <CardBody>
+    Hello! I&apos;m note variant of card.
+  </CardBody>
+  <CardFooter>
+    <Button label="Read more" priority="outline" color="note" />
+  </CardFooter>
+</Card>
+<Card>
+  <CardBody>
+    Hello! I&apos;m light (default) variant of card.
+  </CardBody>
+  <CardFooter>
+    <Button label="Read more" priority="outline" color="dark" />
+  </CardFooter>
+</Card>
+<Card color="dark">
+  <CardBody>
+    Hello! I&apos;m dark variant of card.
+  </CardBody>
+  <CardFooter>
+    <Button label="Read more" priority="outline" color="light" />
+  </CardFooter>
+</Card>
+```
+
+## States
+
+### Disabled State
+
+Entire card can appear disabled. However, you'll still need to manually disable
+its interactive elements to disallow user's interaction.
+
+```docoff-react-preview
+<Card disabled>
+  <CardBody>
+    Hello! I&apos;m a disabled card.
+  </CardBody>
+  <CardFooter>
+    <Button label="Read more" priority="outline" disabled />
+  </CardFooter>
+</Card>
+<Card disabled raised>
+  <CardBody>
+    Hello! I&apos;m a disabled raised card.
+  </CardBody>
+  <CardFooter>
+    <Button label="Read more" priority="outline" disabled />
+  </CardFooter>
+</Card>
+<Card color="success" disabled>
+  <CardBody>
+    Hello! I&apos;m a disabled success variant of card.
+  </CardBody>
+  <CardFooter>
+    <Button label="Read more" priority="outline" color="success" disabled />
+  </CardFooter>
+</Card>
+```
+
+## 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/Card/Card.jsx"></docoff-react-props>
+
+### CardBody
+
+Space your content with CardBody. See [Composition](#composition) for
+all details.
+
+<docoff-react-props src="/components/Card/CardBody.jsx"></docoff-react-props>
+
+### CardFooter
+
+Separate your card actions with CardFooter. See
+[Composition](#composition) for all details.
+
+<docoff-react-props src="/components/Card/CardFooter.jsx"></docoff-react-props>
+
+## Theming
+
+### Common Theming Options
+
+| Custom Property                                      | Description                                                  |
+|------------------------------------------------------|--------------------------------------------------------------|
+| `--rui-Card__padding`                                | Padding shared by card header, body and footer               |
+| `--rui-Card__border-width`                           | Border width                                                 |
+| `--rui-Card__border-radius`                          | Corner radius                                                |
+| `--rui-Card--dense__padding`                         | Padding of dense card                                        |
+| `--rui-Card--raised__box-shadow`                     | Box shadow of raised card                                    |
+| `--rui-Card--disabled__background-color`             | Card background color in disabled state                      |
+| `--rui-Card--disabled__opacity`                      | Card opacity in disabled state                               |
+
+### Theming Variants
+
+It's possible to adjust the theme of specific color variant. Naming convention
+looks as follows:
+
+`--rui-Card--<COLOR>__<PROPERTY>`
+
+Where:
+
+- `<COLOR>` is one of supported
+  [component colors](/docs/foundation/colors#component-colors)
+  (see [color variants](#color-variants) and [API](#api)),
+- `<PROPERTY>` is one of `color` (color of text), `border-color`, or
+  `background-color`.
+
+[React synthetic events]: https://reactjs.org/docs/events.html
+[div]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/div#attributes