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 { TextLink } from '../Link/TextLink.tsx';
|
||||
import { Basic } from './Text.internal.story.tsx';
|
||||
import { Tooltip } from '../Tooltip';
|
||||
|
||||
<Meta title="MDX|Text" component={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