import { Meta, Canvas, ArgTypes } from '@storybook/blocks'; import { Text } from './Text'; import { TextLink } from '../Link/TextLink.tsx'; import { Basic } from './Text.story.tsx'; import { Tooltip } from '../Tooltip/Tooltip'; import { ExampleFrame } from '../../utils/storybook/ExampleFrame';

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:

Usage
Content
Formating
1. Anatomy
2. Behaviour
Accessibility
Props table

<a name="usage"/> Usage

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.
Use the tabular prop when numbers should have a fixed width, such as in tables.

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.
Do not use the code variant for anything other than code snippets.

<a name="content"/> Content

The content of the text should be written according to the Grafana writing 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:

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

<ExampleFrame> <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> </ExampleFrame> <ExampleFrame> <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> </ExampleFrame>

<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.

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.

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

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.

<ExampleFrame> <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> </ExampleFrame>

<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