Add align prop to Text component (#341)

.changeset/metal-feet-work.md

@@ -0,0 +1,19 @@
+---
+'@primer/react-brand': patch
+---
+
+Added optional `align` prop to Text component.
+
+```jsx
+<>
+  <Text as="p" align="start">
+    Start
+  </Text>
+  <Text as="p" align="center">
+    Center
+  </Text>
+  <Text as="p" align="end">
+    End
+  </Text>
+</>
+```

apps/docs/content/components/Text/index.mdx

@@ -44,8 +44,8 @@ The text size ranges from 100 to 700, with 400 as the default size. This scale i
     <img src="https://github.com/primer/brand/assets/912236/e029b053-eab8-47a7-bd49-b6ce49ac8bdf" />
     <Caption>
       Use a smaller size to provide visual hierarchy when the text is paired
-      with a title. Use as many text components as needed to represent different blocks of
-      content.
+      with a title. Use as many text components as needed to represent different
+      blocks of content.
     </Caption>
   </Do>
   <Dont>
@@ -57,6 +57,12 @@ The text size ranges from 100 to 700, with 400 as the default size. This scale i
   </Dont>
 </DoDontContainer>
 
+### Alignment
+
+Text alignment options offer a convenient way to control the positioning of content within block level elements.
+
+Available options include `start`, `center`, and `end`, which are recommended for supporting bidirectional reading.
+
 ### Weight
 
 The text component also supports `weight` options. Weight is automatically determined by the text size, but can be overridden when the scenario calls for it.

apps/docs/content/components/Text/react.mdx

@@ -58,6 +58,24 @@ import {Text} from '@primer/react-brand'
 </>
 ```
 
+### Alignment
+
+Use `align` to set the horizontal alignment of content inside a block element.
+
+```jsx live
+<Stack direction="vertical">
+  <Text as="p" align="start">
+    Start
+  </Text>
+  <Text as="p" align="center">
+    Center
+  </Text>
+  <Text as="p" align="end">
+    End
+  </Text>
+</Stack>
+```
+
 ### Polymorphism
 
 The `Text` component can render as a `span`, `p` or `div` HTML element.

packages/e2e/scripts/playwright/playwright.generate-tests.ts

@@ -65,7 +65,8 @@
     'components-actionmenu-features--open-by-default': 1000, // for the menu to open
     'components-actionmenu-features--longer-lists-open': 1000, // for the menu to open
     'components-actionmenu-features--menu-alignment': 1000, // for the menu to open
-    'components-actionmenu-features--disabled-item': 1000, // flakey test
+    'components-actionmenu-features--disabled-item': 1000, // flakey test,
+    'components-box-features--animation': 6000, // for the animation
   }
 
   /**

packages/react/src/Box/Box.visual.spec.ts

@@ -14,36 +14,36 @@ test.describe('Visual Comparison: Box', () => {
     expect(await page.screenshot()).toMatchSnapshot()
   })
 
-  test('Box / Directional Padding: Top', async ({page}) => {
+  test('Box / Directional Padding: Block start (top)', async ({page}) => {
     await page.goto(
-      'http://localhost:6006/iframe.html?args=&id=components-box-features--directional-padding-top&viewMode=story',
+      'http://localhost:6006/iframe.html?args=&id=components-box-features--directional-padding-block-start&viewMode=story',
     )
 
     await page.waitForTimeout(500)
     expect(await page.screenshot()).toMatchSnapshot()
   })
 
-  test('Box / Directional Padding: Right', async ({page}) => {
+  test('Box / Directional Padding: Inline end (right)', async ({page}) => {
     await page.goto(
-      'http://localhost:6006/iframe.html?args=&id=components-box-features--directional-padding-right&viewMode=story',
+      'http://localhost:6006/iframe.html?args=&id=components-box-features--directional-padding-inline-end&viewMode=story',
     )
 
     await page.waitForTimeout(500)
     expect(await page.screenshot()).toMatchSnapshot()
   })
 
-  test('Box / Directional Padding: Bottom', async ({page}) => {
+  test('Box / Directional Padding: Block end (bottom)', async ({page}) => {
     await page.goto(
-      'http://localhost:6006/iframe.html?args=&id=components-box-features--directional-padding-bottom&viewMode=story',
+      'http://localhost:6006/iframe.html?args=&id=components-box-features--directional-padding-block-end&viewMode=story',
     )
 
     await page.waitForTimeout(500)
     expect(await page.screenshot()).toMatchSnapshot()
   })
 
-  test('Box / Directional Padding: Left', async ({page}) => {
+  test('Box / Directional Padding: Inline start (left)', async ({page}) => {
     await page.goto(
-      'http://localhost:6006/iframe.html?args=&id=components-box-features--directional-padding-left&viewMode=story',
+      'http://localhost:6006/iframe.html?args=&id=components-box-features--directional-padding-inline-start&viewMode=story',
     )
 
     await page.waitForTimeout(500)
@@ -57,16 +57,16 @@ test.describe('Visual Comparison: Box', () => {
     expect(await page.screenshot()).toMatchSnapshot()
   })
 
-  test('Box / Directional Margin: Top', async ({page}) => {
+  test('Box / Directional Margin: Block start (top)', async ({page}) => {
     await page.goto(
-      'http://localhost:6006/iframe.html?args=&id=components-box-features--directional-margin-top&viewMode=story',
+      'http://localhost:6006/iframe.html?args=&id=components-box-features--directional-margin-block-start&viewMode=story',
     )
 
     await page.waitForTimeout(500)
     expect(await page.screenshot()).toMatchSnapshot()
   })
 
-  test('Box / Directional Margin: Right', async ({page}) => {
+  test('Box / Directional Margin: Inline end (right)', async ({page}) => {
     await page.goto(
       'http://localhost:6006/iframe.html?args=&id=components-box-features--directional-margin-right&viewMode=story',
     )
@@ -75,7 +75,7 @@ test.describe('Visual Comparison: Box', () => {
     expect(await page.screenshot()).toMatchSnapshot()
   })
 
-  test('Box / Directional Margin: Bottom', async ({page}) => {
+  test('Box / Directional Margin: Block end (bottom)', async ({page}) => {
     await page.goto(
       'http://localhost:6006/iframe.html?args=&id=components-box-features--directional-margin-bottom&viewMode=story',
     )
@@ -84,7 +84,7 @@ test.describe('Visual Comparison: Box', () => {
     expect(await page.screenshot()).toMatchSnapshot()
   })
 
-  test('Box / Directional Margin: Left', async ({page}) => {
+  test('Box / Directional Margin: Inline start (left)', async ({page}) => {
     await page.goto(
       'http://localhost:6006/iframe.html?args=&id=components-box-features--directional-margin-left&viewMode=story',
     )
@@ -126,7 +126,7 @@ test.describe('Visual Comparison: Box', () => {
   test('Box / Animation', async ({page}) => {
     await page.goto('http://localhost:6006/iframe.html?args=&id=components-box-features--animation&viewMode=story')
 
-    await page.waitForTimeout(500)
+    await page.waitForTimeout(6000)
     expect(await page.screenshot()).toMatchSnapshot()
   })
 

packages/react/src/Prose/Prose.features.stories.tsx

@@ -2,6 +2,7 @@ import React from 'react'
 import {ComponentMeta, ComponentStory} from '@storybook/react'
 import {INITIAL_VIEWPORTS} from '@storybook/addon-viewport'
 import {Prose} from './Prose'
+import placeholderImage from '../fixtures/images/placeholder-600x400.png'
 
 export default {
   title: 'Components/Prose/Features',
@@ -30,7 +31,7 @@ const ExampleHtmlMarkup = `
     <h3>Heading level 3</h3>
     <p>Pellentesque non ornare ligula. Suspendisse nibh purus, pretium id tortor sit amet, tincidunt gravida augue. Ut malesuada, nisl vel dignissim mollis</p>
     <img
-      src="https://via.placeholder.com/400x400/f5f5f5/f5f5f5.png"
+      src="${placeholderImage}"
       alt="placeholder, blank area with an off-white background color"
       />
     <h4>Heading level  4</h4>

packages/react/src/Prose/Prose.stories.tsx

@@ -1,6 +1,7 @@
 import React from 'react'
 import {ComponentMeta, ComponentStory} from '@storybook/react'
 import {Prose} from './Prose'
+import placeholderImage from '../fixtures/images/placeholder-600x400.png'
 
 export default {
   title: 'Components/Prose',
@@ -34,7 +35,7 @@ const ExampleHtmlMarkup = `
     <h3>Heading level 3</h3>
     <p>Pellentesque non ornare ligula. Suspendisse nibh purus, pretium id tortor sit amet, tincidunt gravida augue. Ut malesuada, nisl vel dignissim mollis</p>
     <img
-      src="https://via.placeholder.com/400x400/f5f5f5/f5f5f5.png"
+      src="${placeholderImage}"
       alt="placeholder, blank area with an off-white background color"
       />
     <h4>Heading level  4</h4>

packages/react/src/Text/Text.module.css

@@ -147,3 +147,15 @@
     font-weight: var(--base-text-weight-light);
   }
 }
+
+.Text-align--start {
+  text-align: start;
+}
+
+.Text-align--end {
+  text-align: end;
+}
+
+.Text-align--center {
+  text-align: center;
+}

packages/react/src/Text/Text.module.css.d.ts

@@ -37,6 +37,9 @@ declare const styles: {
   readonly "Text-wide--weight-medium": string;
   readonly "Text-wide--weight-normal": string;
   readonly "Text-wide--weight-light": string;
+  readonly "Text-align--start": string;
+  readonly "Text-align--end": string;
+  readonly "Text-align--center": string;
 };
 export = styles;
 

packages/react/src/Text/Text.stories.tsx

@@ -1,6 +1,7 @@
 import {Meta, StoryFn} from '@storybook/react'
 import React from 'react'
 import {Text, TextSizes, TextWeights} from '.'
+import {Stack} from '../Stack'
 
 export default {
   title: 'Components/Text',
@@ -60,3 +61,18 @@ export const Composition = () => (
     on improving collaboration, security practices, and developer productivity is right around the corner.
   </Text>
 )
+
+export const Alignment = () => (
+  <Stack direction="vertical">
+    <Text as="p">Default</Text>
+    <Text as="p" align="start">
+      Start
+    </Text>
+    <Text as="p" align="center">
+      Center
+    </Text>
+    <Text as="p" align="end">
+      End
+    </Text>
+  </Stack>
+)

packages/react/src/Text/Text.tsx

@@ -50,9 +50,16 @@ export type TextProps = {
    * Specify the text weight
    */
   weight?: TextWeightVariants | ResponsiveWeightMap
+  /**
+   * Specify the text alignment.
+   * Corresponds to the CSS `text-align` property.
+   * Note: Only applies to block elements.
+   */
+  align?: 'start' | 'center' | 'end'
 } & TextTags
 
 export function Text({
+  align,
   animate,
   as = defaultTextTag,
   className,
@@ -83,6 +90,7 @@ export function Text({
     styles[`Text--${variant}`],
     styles[`Text--${size}`],
     weight && weightClass,
+    align && styles[`Text-align--${align}`],
     className,
   )
 

packages/react/src/Text/Text.visual.spec.ts

@@ -43,4 +43,11 @@ test.describe('Visual Comparison: Text', () => {
     await page.waitForTimeout(500)
     expect(await page.screenshot()).toMatchSnapshot()
   })
+
+  test('Text / Alignment', async ({page}) => {
+    await page.goto('http://localhost:6006/iframe.html?args=&id=components-text--alignment&viewMode=story')
+
+    await page.waitForTimeout(500)
+    expect(await page.screenshot()).toMatchSnapshot()
+  })
 })