docs: refactor Text documentation and add missing guidance for preset…

…s/alignment (microsoft#25587)

Fixes microsoft#24341
Fixes microsoft#25548

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": "[email protected]",
+  "dependentChangeType": "none"
+}

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

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>
+  );
+};

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>

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>
+  );
+};

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

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,
+    },
+  },
+};

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>
+  );
+};

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>
+  );
+};

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>
+  );
+};

packages/react-components/react-text/stories/Text/index.stories.tsx

@@ -1,25 +1,26 @@
 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',
   component: Text,
   parameters: {
     docs: {
       description: {
-        component: [textDescriptionMd, textBestPractices].join('\n'),
+        component: [textDescriptionMd, textBestPracticesMd].join('\n'),
       },
     },
   },