grafana/packages/grafana-ui/src/components/Text/Text.mdx

import { Meta, Props, Preview, ArgsTable } from '@storybook/addon-docs/blocks';
import { Text } from './Text';
import { TextLink } from '../Link/TextLink.tsx';
import { Basic } from './Text.internal.story.tsx';
import { Tooltip } from '../Tooltip';

<Meta title="MDX|Text" component={Text} />

# Text

The Text component can be used to apply typography styles in a simple way, without the need of extra css.

---

In this documentation you can find:

1. [Usage](#usage)
1. [Content](#content)
1. [Formating](#formating)
   1. [Anatomy](#anatomy)
   1. [Behaviour](#behaviour)
1. [Accessibility](#accessibility)
1. [Props table](#propstable)

<br />
<br />

## <a name="usage"/> Usage

<br />

### **When to use**

- To display text, with styles applied consistently across the product, and to provide structure to each page.

### **When not to use**

- If there is any straightforward interaction between the text and the user there should be a better component to use: Button, TextLink, Menu…

### **Do's**

- Heading should be organized in hierarchy.
- When a heading needs to have the appearance of another heading rank but it will affect the page heading hierarchy, use `variant` prop to modify its style instead.
- Use weight or italic for emphasis.

### **Don'ts**

- Do not use the `element` prop because of its appearance, use it to organize the structure of the page.
- Do not use color for emphasis as colors are related to states such as `error`, `success`, `disabled` and so on.

  <br />
  <br />

## <a name="content"/> Content

The content of the text should be written according to the [Grafana writing style guide](https://grafana.com/docs/writers-toolkit/write/style-guide/).

## <a name="formating"/> Formating

The following is the default behaviour and so, it will be applied according to its type.

### <a name="anatomy"/>**Anatomy**:<br/>

The Text component is mainly comprised by itself. In occasions, the Text component can have another Text or TextLink component as a child.

<Preview>
  <Text color="primary" element="p">
    {'If you need more help of how to write in Grafana you can go to our '}
    <TextLink href="https://grafana.com/docs/writers-toolkit/" external>
      {'Writer’s Toolkit'}
    </TextLink>
  </Text>
</Preview>

```jsx
<Text color="primary" element="p">
  If you need more help of how to write in Grafana you can go to our
  <TextLink href="https://grafana.com/docs/writers-toolkit/" external>
    Writer’s Toolkit
  </TextLink>
</Text>
```

<Preview>
  <Text color="primary" element="p">
    {'And Forrest Gump said: '}
    <Text italic>{"Life is like a box of chocolates. You never know what you're gonna get."}</Text>
  </Text>
</Preview>

```jsx
<Text color="primary" element="p">
  And Forrest Gump said:
  <Text italic>Life is like a box of chocolates. You never know what you're gonna get.</Text>
</Text>
```

### <a name="behaviour"/>**Behaviour**:

The Text component can be truncated. However, the Text component element rendered by default (no value set in element prop) is a `<span>`. As this is an inline container that must have a parent, which can be another Text component or not, the truncation must be applied to this parent element.

1. The parent element is a Text component: the user just has to set the element prop to another value and the truncate prop to true.
   As a result, the Text will be truncated but when the user hovers over it the full text will be seen on a tooltip.

<Preview>
  <Text color="primary" element="p" truncate>
    {'And Forrest Gump said: '}
    <Text italic>{"Life is like a box of chocolates. You never know what you're gonna get."}</Text>
  </Text>
</Preview>

```jsx
<Text color="primary" element="p" truncate>
  And Forrest Gump said:
  <Text italic>Life is like a box of chocolates. You never know what you're gonna get.</Text>
</Text>
```

2. The parent element is not a Text component: the user has to add `overflow: hidden`, `text-overflow: ellipsis` and `whiteSpace: 'nowrap'` to it. In this case, the user should wrap up this container with a Tooltip, so when the text is truncated its content can still be seen hovering on the text.

<Preview>
  <Tooltip content="This is a example of a span element truncated by its parent container">
    <div style={{ overflow: 'hidden', textOverflow: 'ellipsis', whiteSpace: 'nowrap' }}>
      <Text color="primary" variant="body">
        {'This is a example of a span element truncated by its parent container.'}
      </Text>
    </div>
  </Tooltip>
</Preview>
```jsx
<Tooltip content="This is a example of a span element truncated by its parent container">
  <div style={{ overflow: 'hidden', textOverflow: 'ellipsis', whiteSpace: 'nowrap' }}>
    <Text color="primary" variant="body">
      {'This is a example of a span element truncated by its parent container.'}
    </Text>
  </div>
</Tooltip>
```

### <a name="accessibility"/>**Accessibility**:

- There should be just a `h1` heading per page.
- The headings should be organized regarding its importance: `h1` has the _rank 1_ while `h6` heading has the _rank 6_. For example, `h1` can be used in the page heading, `h2` for the titles of the sections and `h3` for the subsections.
- The ranking of headings should be continuous. An `h2` should not be followed by an `h5` but an `h2` can follow an `h5` if this is closing the previous section. Skipping heading ranks should be avoided where possible as it can be confusing.

## <a name="propstable"/>Props table

<ArgsTable of={Text} />