mirror of
https://github.com/grafana/grafana.git
synced 2025-02-25 18:55:37 -06:00
Grafana-ui: Text component documentation in Storybook (#72389)
This commit is contained in:
Laura Fernández
GitHub
parent
0d121bab29
commit
0fa20b7152
@ -1,8 +1,148 @@
|
|||||||
import { Props, ArgTypes } from '@storybook/blocks';
|
import { Meta, Props, Preview, ArgsTable } from '@storybook/addon-docs/blocks';
|
||||||
import { Text } from './Text';
|
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
|
# Text
|
||||||
|
|
||||||
Use for showing text.
|
The Text component can be used to apply typography styles in a simple way, without the need of extra css.
|
||||||
|
|
||||||
<ArgTypes of={Text} />
|
---
|
||||||
|
|
||||||
|
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} />
|
||||||
|
|||||||
109
packages/grafana-ui/src/components/Text/Text.story.internal.tsx
Normal file
109
packages/grafana-ui/src/components/Text/Text.story.internal.tsx
Normal file
@ -0,0 +1,109 @@
|
|||||||
|
import { Meta, StoryFn } from '@storybook/react';
|
||||||
|
import React from 'react';
|
||||||
|
|
||||||
|
import { StoryExample } from '../../utils/storybook/StoryExample';
|
||||||
|
import { VerticalGroup } from '../Layout/Layout';
|
||||||
|
|
||||||
|
import { Text } from './Text';
|
||||||
|
import mdx from './Text.mdx';
|
||||||
|
|
||||||
|
const meta: Meta = {
|
||||||
|
title: 'General/Text',
|
||||||
|
component: Text,
|
||||||
|
parameters: {
|
||||||
|
docs: {
|
||||||
|
page: mdx,
|
||||||
|
},
|
||||||
|
},
|
||||||
|
argTypes: {
|
||||||
|
variant: { control: 'select', options: ['h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'body', 'bodySmall', undefined] },
|
||||||
|
weight: {
|
||||||
|
control: 'select',
|
||||||
|
options: ['bold', 'medium', 'light', 'regular', undefined],
|
||||||
|
},
|
||||||
|
color: {
|
||||||
|
control: 'select',
|
||||||
|
options: [
|
||||||
|
'error',
|
||||||
|
'success',
|
||||||
|
'warning',
|
||||||
|
'info',
|
||||||
|
'primary',
|
||||||
|
'secondary',
|
||||||
|
'disabled',
|
||||||
|
'link',
|
||||||
|
'maxContrast',
|
||||||
|
undefined,
|
||||||
|
],
|
||||||
|
},
|
||||||
|
truncate: { control: 'boolean' },
|
||||||
|
italic: { control: 'boolean' },
|
||||||
|
textAlignment: {
|
||||||
|
control: 'select',
|
||||||
|
options: ['inherit', 'initial', 'left', 'right', 'center', 'justify', undefined],
|
||||||
|
},
|
||||||
|
},
|
||||||
|
args: {
|
||||||
|
element: 'h1',
|
||||||
|
variant: undefined,
|
||||||
|
weight: 'light',
|
||||||
|
textAlignment: 'left',
|
||||||
|
truncate: false,
|
||||||
|
italic: false,
|
||||||
|
color: 'primary',
|
||||||
|
children: `This is an example of a Text component`,
|
||||||
|
},
|
||||||
|
};
|
||||||
|
|
||||||
|
export const Example: StoryFn = (args) => {
|
||||||
|
return (
|
||||||
|
<VerticalGroup>
|
||||||
|
<StoryExample name="Header, paragraph and span">
|
||||||
|
<Text {...args} element="h1">
|
||||||
|
This is a header
|
||||||
|
</Text>
|
||||||
|
<Text {...args} element="p">
|
||||||
|
This is a paragraph that contains
|
||||||
|
<Text color="success" italic>
|
||||||
|
{' '}
|
||||||
|
a span element with different color and style{' '}
|
||||||
|
</Text>
|
||||||
|
but is comprised within the same block text
|
||||||
|
</Text>
|
||||||
|
</StoryExample>
|
||||||
|
<StoryExample name="Paragraph with truncate set to true and wrapping up a span element">
|
||||||
|
<Text {...args} element="p" truncate>
|
||||||
|
This is a paragraph that contains
|
||||||
|
<Text color="warning" italic>
|
||||||
|
{' '}
|
||||||
|
a span element{' '}
|
||||||
|
</Text>
|
||||||
|
but has truncate set to true
|
||||||
|
</Text>
|
||||||
|
</StoryExample>
|
||||||
|
</VerticalGroup>
|
||||||
|
);
|
||||||
|
};
|
||||||
|
Example.parameters = {
|
||||||
|
controls: {
|
||||||
|
exclude: ['element', 'variant', 'weight', 'textAlignment', 'truncate', 'italic', 'color', 'children'],
|
||||||
|
},
|
||||||
|
};
|
||||||
|
|
||||||
|
export const Basic: StoryFn = (args) => {
|
||||||
|
return (
|
||||||
|
<div style={{ width: '300px' }}>
|
||||||
|
<Text
|
||||||
|
element={args.element}
|
||||||
|
variant={args.variant}
|
||||||
|
weight={args.weight}
|
||||||
|
textAlignment={args.textAlignment}
|
||||||
|
{...args}
|
||||||
|
>
|
||||||
|
{args.children}
|
||||||
|
</Text>
|
||||||
|
</div>
|
||||||
|
);
|
||||||
|
};
|
||||||
|
|
||||||
|
export default meta;
|
||||||
Loading…
Reference in New Issue
Block a user