From a251bd18fe19369e1d9001940c5d31c9484b48f5 Mon Sep 17 00:00:00 2001
From: Marcos Moura <marcosvmmoura@gmail.com>
Date: Fri, 11 Nov 2022 13:58:30 +0100
Subject: [PATCH] docs: refactor Text documentation and add missing guidance
 for presets/alignment (#25587)

Fixes https://github.com/microsoft/fluentui/issues/24341
Fixes https://github.com/microsoft/fluentui/issues/25548
---
 ...-a9af2339-7549-4913-aa3f-8542dfffd971.json |  7 +++
 .../stories/Text/Default.stories.tsx          | 18 +------
 .../stories/Text/TextAlignment.stories.tsx    | 30 +++++++++++
 .../stories/Text/TextBestPractices.md         |  7 ++-
 .../stories/Text/TextFont.stories.tsx         | 28 +++++++---
 .../react-text/stories/Text/TextPresets.md    |  1 +
 .../stories/Text/TextPresets.stories.tsx      | 52 +++++++++++++++++++
 .../stories/Text/TextSize.stories.tsx         | 43 +++++++++------
 .../stories/Text/TextTruncate.stories.tsx     | 25 ++++++---
 .../stories/Text/TextTypography.stories.tsx   | 39 --------------
 .../stories/Text/TextWeight.stories.tsx       | 29 ++++++++---
 .../react-text/stories/Text/index.stories.tsx | 13 ++---
 12 files changed, 190 insertions(+), 102 deletions(-)
 create mode 100644 change/@fluentui-react-text-a9af2339-7549-4913-aa3f-8542dfffd971.json
 create mode 100644 packages/react-components/react-text/stories/Text/TextAlignment.stories.tsx
 create mode 100644 packages/react-components/react-text/stories/Text/TextPresets.md
 create mode 100644 packages/react-components/react-text/stories/Text/TextPresets.stories.tsx
 delete mode 100644 packages/react-components/react-text/stories/Text/TextTypography.stories.tsx

diff --git a/change/@fluentui-react-text-a9af2339-7549-4913-aa3f-8542dfffd971.json b/change/@fluentui-react-text-a9af2339-7549-4913-aa3f-8542dfffd971.json
new file mode 100644
index 0000000000000..4021cf9cf19a8
--- /dev/null
+++ b/change/@fluentui-react-text-a9af2339-7549-4913-aa3f-8542dfffd971.json
@@ -0,0 +1,7 @@
+{
+  "type": "none",
+  "comment": "refactor Text documentation and add missing guidance for presets/alignment",
+  "packageName": "@fluentui/react-text",
+  "email": "marcosvmmoura@gmail.com",
+  "dependentChangeType": "none"
+}
diff --git a/packages/react-components/react-text/stories/Text/Default.stories.tsx b/packages/react-components/react-text/stories/Text/Default.stories.tsx
index 7236387cb183f..903b1dc887df4 100644
--- a/packages/react-components/react-text/stories/Text/Default.stories.tsx
+++ b/packages/react-components/react-text/stories/Text/Default.stories.tsx
@@ -1,18 +1,4 @@
 import * as React from 'react';
-import { makeStyles, Text } from '@fluentui/react-components';
-import type { TextProps } from '@fluentui/react-components';
+import { Text } from '@fluentui/react-components';
 
-const useStyles = makeStyles({
-  container: {
-    width: '100px',
-  },
-});
-
-export const Default = (props: TextProps) => {
-  const styles = useStyles();
-  return (
-    <div className={styles.container}>
-      <Text {...props}>This is an example of the Text component's usage.</Text>
-    </div>
-  );
-};
+export const Default = () => <Text>This is an example of the Text component's usage.</Text>;
diff --git a/packages/react-components/react-text/stories/Text/TextAlignment.stories.tsx b/packages/react-components/react-text/stories/Text/TextAlignment.stories.tsx
new file mode 100644
index 0000000000000..078c8c00dd3da
--- /dev/null
+++ b/packages/react-components/react-text/stories/Text/TextAlignment.stories.tsx
@@ -0,0 +1,30 @@
+import * as React from 'react';
+import { makeStyles, shorthands, Text } from '@fluentui/react-components';
+
+const useStyles = makeStyles({
+  container: {
+    ...shorthands.gap('16px'),
+    display: 'flex',
+    flexDirection: 'column',
+    alignItems: 'stretch',
+  },
+});
+
+export const Alignment = () => {
+  const styles = useStyles();
+
+  return (
+    <div className={styles.container}>
+      <Text align="start">Aligned to start</Text>
+      <Text align="center">Aligned to center</Text>
+      <Text align="end">Aligned to end</Text>
+      <Text align="justify">
+        Justified text: Lorem ipsum dolor sit amet consectetur adipisicing elit. Praesentium accusamus voluptate autem?
+        Recusandae alias corporis dicta quisquam sequi molestias deleniti, libero necessitatibus, eligendi, omnis cumque
+        enim asperiores quasi quidem sit. Lorem ipsum dolor sit amet, consectetur adipisicing elit. Possimus repellat
+        consectetur, sed aperiam ex nulla repellendus tempora vero illo aliquam autem! Impedit ipsa praesentium vero
+        veritatis unde eos, fuga magnam!
+      </Text>
+    </div>
+  );
+};
diff --git a/packages/react-components/react-text/stories/Text/TextBestPractices.md b/packages/react-components/react-text/stories/Text/TextBestPractices.md
index 1ba2c4a948e45..96a21338813b5 100644
--- a/packages/react-components/react-text/stories/Text/TextBestPractices.md
+++ b/packages/react-components/react-text/stories/Text/TextBestPractices.md
@@ -1,12 +1,11 @@
 <details>
-<summary>
- Best Practices
-</summary>
+  <summary>
+    Best Practices
+  </summary>
 
 ### Do
 
 - Use Text whenever you need to display stylized text
 - Use Text to display read-only text
 - Use the `as` prop to give the text a semantic meaning. By default, the Text component will result in a `span` element.
-
 </details>
diff --git a/packages/react-components/react-text/stories/Text/TextFont.stories.tsx b/packages/react-components/react-text/stories/Text/TextFont.stories.tsx
index 09830435a630b..e9620964dc95a 100644
--- a/packages/react-components/react-text/stories/Text/TextFont.stories.tsx
+++ b/packages/react-components/react-text/stories/Text/TextFont.stories.tsx
@@ -1,10 +1,22 @@
 import * as React from 'react';
-import { Text } from '@fluentui/react-components';
+import { makeStyles, shorthands, Text } from '@fluentui/react-components';
 
-export const Font = () => (
-  <div style={{ display: 'flex', gap: 20 }}>
-    <Text font="base">This is the default font</Text>
-    <Text font="numeric">This is numeric font</Text>
-    <Text font="monospace">This is monospace font</Text>
-  </div>
-);
+const useStyles = makeStyles({
+  container: {
+    ...shorthands.gap('16px'),
+    display: 'flex',
+    flexDirection: 'column',
+  },
+});
+
+export const Font = () => {
+  const styles = useStyles();
+
+  return (
+    <div className={styles.container}>
+      <Text font="base">This is the default font</Text>
+      <Text font="numeric">This is numeric font</Text>
+      <Text font="monospace">This is monospace font</Text>
+    </div>
+  );
+};
diff --git a/packages/react-components/react-text/stories/Text/TextPresets.md b/packages/react-components/react-text/stories/Text/TextPresets.md
new file mode 100644
index 0000000000000..7a14ab32d34f9
--- /dev/null
+++ b/packages/react-components/react-text/stories/Text/TextPresets.md
@@ -0,0 +1 @@
+**Presets** are a set of components with predefined styles for typography. They are used to create and share a consistent look and feel.<br> All the base `Text` props can be used, except for `font`, `size` and `weight`.
diff --git a/packages/react-components/react-text/stories/Text/TextPresets.stories.tsx b/packages/react-components/react-text/stories/Text/TextPresets.stories.tsx
new file mode 100644
index 0000000000000..6fd0e3fd584ea
--- /dev/null
+++ b/packages/react-components/react-text/stories/Text/TextPresets.stories.tsx
@@ -0,0 +1,52 @@
+import * as React from 'react';
+import {
+  makeStyles,
+  shorthands,
+  Body1,
+  Caption1,
+  Caption2,
+  Display,
+  LargeTitle,
+  Subtitle1,
+  Subtitle2,
+  Title1,
+  Title2,
+  Title3,
+} from '@fluentui/react-components';
+import textPresetsMd from './TextPresets.md';
+
+const useStyles = makeStyles({
+  container: {
+    ...shorthands.gap('16px'),
+    display: 'flex',
+    flexDirection: 'column',
+    alignItems: 'baseline',
+  },
+});
+
+export const Presets = () => {
+  const styles = useStyles();
+
+  return (
+    <div className={styles.container}>
+      <Display>Display - semibold, base1000</Display>
+      <LargeTitle>LargeTitle - semibold, base900</LargeTitle>
+      <Title1>Title1 - semibold, base800</Title1>
+      <Title2>Title2 - semibold, base700</Title2>
+      <Title3>Title3 - semibold, base600</Title3>
+      <Subtitle1>Subtitle1 - semibold, base500</Subtitle1>
+      <Subtitle2>Subtitle2 - semibold, base400</Subtitle2>
+      <Body1>Body1 - regular, base300</Body1>
+      <Caption1>Caption1 - regular, base200</Caption1>
+      <Caption2>Caption2 - regular, base100</Caption2>
+    </div>
+  );
+};
+
+Presets.parameters = {
+  docs: {
+    description: {
+      story: textPresetsMd,
+    },
+  },
+};
diff --git a/packages/react-components/react-text/stories/Text/TextSize.stories.tsx b/packages/react-components/react-text/stories/Text/TextSize.stories.tsx
index 7f3b7467e7594..be8dec81c4331 100644
--- a/packages/react-components/react-text/stories/Text/TextSize.stories.tsx
+++ b/packages/react-components/react-text/stories/Text/TextSize.stories.tsx
@@ -1,17 +1,30 @@
 import * as React from 'react';
-import { Text } from '@fluentui/react-components';
+import { makeStyles, shorthands, Text } from '@fluentui/react-components';
 
-export const Size = () => (
-  <div style={{ display: 'flex', gap: 10, alignItems: 'baseline' }}>
-    <Text size={100}> 100 </Text>
-    <Text size={200}> 200 </Text>
-    <Text size={300}> 300 </Text>
-    <Text size={400}> 400 </Text>
-    <Text size={500}> 500 </Text>
-    <Text size={600}> 600 </Text>
-    <Text size={700}> 700 </Text>
-    <Text size={800}> 800 </Text>
-    <Text size={900}> 900 </Text>
-    <Text size={1000}>1000 </Text>
-  </div>
-);
+const useStyles = makeStyles({
+  container: {
+    ...shorthands.gap('16px'),
+    display: 'flex',
+    flexDirection: 'column',
+    alignItems: 'baseline',
+  },
+});
+
+export const Size = () => {
+  const styles = useStyles();
+
+  return (
+    <div className={styles.container}>
+      <Text size={100}>100</Text>
+      <Text size={200}>200</Text>
+      <Text size={300}>300</Text>
+      <Text size={400}>400</Text>
+      <Text size={500}>500</Text>
+      <Text size={600}>600</Text>
+      <Text size={700}>700</Text>
+      <Text size={800}>800</Text>
+      <Text size={900}>900</Text>
+      <Text size={1000}>1000</Text>
+    </div>
+  );
+};
diff --git a/packages/react-components/react-text/stories/Text/TextTruncate.stories.tsx b/packages/react-components/react-text/stories/Text/TextTruncate.stories.tsx
index 764e15474dd4b..1677de74f286e 100644
--- a/packages/react-components/react-text/stories/Text/TextTruncate.stories.tsx
+++ b/packages/react-components/react-text/stories/Text/TextTruncate.stories.tsx
@@ -1,8 +1,21 @@
 import * as React from 'react';
-import { Text } from '@fluentui/react-components';
+import { makeStyles, shorthands, Text } from '@fluentui/react-components';
 
-export const Truncate = () => (
-  <Text truncate style={{ width: 100, overflow: 'hidden', whiteSpace: 'nowrap' }} block>
-    This is a really really really really long text
-  </Text>
-);
+const useStyles = makeStyles({
+  text: {
+    ...shorthands.overflow('hidden'),
+    width: '240px',
+    display: 'block',
+  },
+});
+
+export const Truncate = () => {
+  const styles = useStyles();
+
+  return (
+    <Text truncate wrap={false} className={styles.text}>
+      Lorem ipsum dolor sit, amet consectetur adipisicing elit. Facere aliquam nisi numquam, fugit recusandae eligendi
+      aspernatur odio minus? Incidunt maxime ipsam dolorem quia quas aliquam, quasi consequatur! Ea, minus eaque.
+    </Text>
+  );
+};
diff --git a/packages/react-components/react-text/stories/Text/TextTypography.stories.tsx b/packages/react-components/react-text/stories/Text/TextTypography.stories.tsx
deleted file mode 100644
index cf888b6d23d01..0000000000000
--- a/packages/react-components/react-text/stories/Text/TextTypography.stories.tsx
+++ /dev/null
@@ -1,39 +0,0 @@
-import * as React from 'react';
-import {
-  Body1,
-  Caption1,
-  Caption2,
-  Display,
-  LargeTitle,
-  Subtitle1,
-  Subtitle2,
-  Title1,
-  Title2,
-  Title3,
-} from '@fluentui/react-components';
-
-export const Typography = () => (
-  <>
-    <Display block>Display text wrapper, semibold, base1000</Display>
-    <LargeTitle block>LargeTitle text wrapper, semibold, base900</LargeTitle>
-    <Title1 block>Title1 text wrapper, semibold, base800</Title1>
-    <Title2 block>Title2 text wrapper, semibold, base700</Title2>
-    <Title3 block>Title3 text wrapper, semibold, base600</Title3>
-    <Subtitle1 block>Subtitle1 text wrapper, semibold, base500</Subtitle1>
-    <Subtitle2 block>Subtitle2 text wrapper, semibold, base400</Subtitle2>
-    <Body1 block>Body1 text wrapper, regular, base300</Body1>
-    <Caption1 block>Caption1 text wrapper, regular, base200</Caption1>
-    <Caption2 block>Caption2 text wrapper, regular, base100</Caption2>
-  </>
-);
-
-Typography.parameters = {
-  docs: {
-    description: {
-      story: [
-        'Different typography components can be used that are based on the `Text` components.',
-        'They all share the same props and behaviours that are documented here.',
-      ].join('\n'),
-    },
-  },
-};
diff --git a/packages/react-components/react-text/stories/Text/TextWeight.stories.tsx b/packages/react-components/react-text/stories/Text/TextWeight.stories.tsx
index c3f34415d26f4..aa92d9f9abe43 100644
--- a/packages/react-components/react-text/stories/Text/TextWeight.stories.tsx
+++ b/packages/react-components/react-text/stories/Text/TextWeight.stories.tsx
@@ -1,10 +1,23 @@
 import * as React from 'react';
-import { Text } from '@fluentui/react-components';
+import { makeStyles, shorthands, Text } from '@fluentui/react-components';
 
-export const Weight = () => (
-  <div style={{ display: 'flex', gap: 20 }}>
-    <Text weight="regular">Regular weight</Text>
-    <Text weight="medium">Medium weight</Text>
-    <Text weight="semibold">Semibold weight</Text>
-  </div>
-);
+const useStyles = makeStyles({
+  container: {
+    ...shorthands.gap('16px'),
+    display: 'flex',
+    flexDirection: 'column',
+  },
+});
+
+export const Weight = () => {
+  const styles = useStyles();
+
+  return (
+    <div className={styles.container}>
+      <Text weight="regular">Regular weight</Text>
+      <Text weight="medium">Medium weight</Text>
+      <Text weight="semibold">Semibold weight</Text>
+      <Text weight="bold">Bold weight</Text>
+    </div>
+  );
+};
diff --git a/packages/react-components/react-text/stories/Text/index.stories.tsx b/packages/react-components/react-text/stories/Text/index.stories.tsx
index 82c3ca85d89bc..4e8ed5c0da5a6 100644
--- a/packages/react-components/react-text/stories/Text/index.stories.tsx
+++ b/packages/react-components/react-text/stories/Text/index.stories.tsx
@@ -1,17 +1,18 @@
 import { Meta } from '@storybook/react';
 import { Text } from '@fluentui/react-components';
 import textDescriptionMd from './TextDescription.md';
-import textBestPractices from './TextBestPractices.md';
+import textBestPracticesMd from './TextBestPractices.md';
 
 export { Default } from './Default.stories';
-export { Typography } from './TextTypography.stories';
+export { Font } from './TextFont.stories';
+export { Size } from './TextSize.stories';
+export { Weight } from './TextWeight.stories';
 export { Italic } from './TextItalic.stories';
 export { Underline } from './TextUnderline.stories';
 export { StrikeThrough } from './TextStrikeThrough.stories';
-export { Weight } from './TextWeight.stories';
-export { Size } from './TextSize.stories';
 export { Truncate } from './TextTruncate.stories';
-export { Font } from './TextFont.stories';
+export { Alignment } from './TextAlignment.stories';
+export { Presets } from './TextPresets.stories';
 
 export default {
   title: 'Components/Text',
@@ -19,7 +20,7 @@ export default {
   parameters: {
     docs: {
       description: {
-        component: [textDescriptionMd, textBestPractices].join('\n'),
+        component: [textDescriptionMd, textBestPracticesMd].join('\n'),
       },
     },
   },