From 0fa20b715295cc42d7746f97d71c9f23d709d52d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Laura=20Fern=C3=A1ndez?= Date: Fri, 28 Jul 2023 14:58:37 +0200 Subject: [PATCH] Grafana-ui: Text component documentation in Storybook (#72389) --- .../grafana-ui/src/components/Text/Text.mdx | 146 +++++++++++++++++- .../components/Text/Text.story.internal.tsx | 109 +++++++++++++ 2 files changed, 252 insertions(+), 3 deletions(-) create mode 100644 packages/grafana-ui/src/components/Text/Text.story.internal.tsx diff --git a/packages/grafana-ui/src/components/Text/Text.mdx b/packages/grafana-ui/src/components/Text/Text.mdx index 906fe2ccbcc..69996bc3649 100644 --- a/packages/grafana-ui/src/components/Text/Text.mdx +++ b/packages/grafana-ui/src/components/Text/Text.mdx @@ -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'; + + # 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. - +--- + +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) + +
+
+ +## 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. + +### **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. + +
+
+ +## 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/). + +## Formating + +The following is the default behaviour and so, it will be applied according to its type. + +### **Anatomy**:
+ +The Text component is mainly comprised by itself. In occasions, the Text component can have another Text or TextLink component as a child. + + + + {'If you need more help of how to write in Grafana you can go to our '} + + {'Writer’s Toolkit'} + + + + +```jsx + + If you need more help of how to write in Grafana you can go to our + + Writer’s Toolkit + + +``` + + + + {'And Forrest Gump said: '} + {"Life is like a box of chocolates. You never know what you're gonna get."} + + + +```jsx + + And Forrest Gump said: + Life is like a box of chocolates. You never know what you're gonna get. + +``` + +### **Behaviour**: + +The Text component can be truncated. However, the Text component element rendered by default (no value set in element prop) is a ``. 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. + + + + {'And Forrest Gump said: '} + {"Life is like a box of chocolates. You never know what you're gonna get."} + + + +```jsx + + And Forrest Gump said: + Life is like a box of chocolates. You never know what you're gonna get. + +``` + +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. + + + +
+ + {'This is a example of a span element truncated by its parent container.'} + +
+ + +```jsx + +
+ + {'This is a example of a span element truncated by its parent container.'} + +
+ +``` + +### **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. + +## Props table + + diff --git a/packages/grafana-ui/src/components/Text/Text.story.internal.tsx b/packages/grafana-ui/src/components/Text/Text.story.internal.tsx new file mode 100644 index 00000000000..e3ea5b5eea9 --- /dev/null +++ b/packages/grafana-ui/src/components/Text/Text.story.internal.tsx @@ -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 ( + + + + This is a header + + + This is a paragraph that contains + + {' '} + a span element with different color and style{' '} + + but is comprised within the same block text + + + + + This is a paragraph that contains + + {' '} + a span element{' '} + + but has truncate set to true + + + + ); +}; +Example.parameters = { + controls: { + exclude: ['element', 'variant', 'weight', 'textAlignment', 'truncate', 'italic', 'color', 'children'], + }, +}; + +export const Basic: StoryFn = (args) => { + return ( +
+ + {args.children} + +
+ ); +}; + +export default meta;