feat: add TopicTag component

.changeset/three-wombats-invite.md

@@ -0,0 +1,5 @@
+---
+'@primer/react': minor
+---
+
+Add experimental TopicTag and TopicTag.Group components

e2e/components/TopicTag.test.ts

@@ -0,0 +1,69 @@
+import {test, expect} from '@playwright/test'
+import {visit} from '../test-helpers/storybook'
+import {themes} from '../test-helpers/themes'
+import {viewports} from '../test-helpers/viewports'
+
+const stories = [
+  {
+    title: 'Default',
+    id: 'experimental-components-topictag--default',
+  },
+] as const
+
+test.describe('TopicTag', () => {
+  for (const story of stories) {
+    test.describe(story.title, () => {
+      for (const theme of themes) {
+        test.describe(theme, () => {
+          test('default @vrt', async ({page}) => {
+            await visit(page, {
+              id: story.id,
+              globals: {
+                colorScheme: theme,
+              },
+            })
+            await page.setViewportSize({width: 400, height: 200})
+
+            // Default state
+            await expect(page).toHaveScreenshot(`TopicTag.${story.title}.${theme}.png`)
+
+            // Hover state
+            await page.getByText('React').hover()
+            await expect(page).toHaveScreenshot(`TopicTag.${story.title}.${theme}.hover.png`)
+
+            // Focus state
+            // eslint-disable-next-line github/no-blur
+            await page.getByText('React').blur()
+            await page.getByText('React').focus()
+            await expect(page).toHaveScreenshot(`TopicTag.${story.title}.${theme}.focus.png`)
+          })
+        })
+      }
+    })
+  }
+
+  test.describe('As Group', () => {
+    const story = {
+      title: 'As Group',
+      id: 'experimental-components-topictag-features--as-group',
+    }
+
+    test('default @vrt', async ({page}) => {
+      await visit(page, {
+        id: story.id,
+      })
+
+      // Viewport: xs
+      await page.setViewportSize({width: viewports['primer.breakpoint.xs'], height: 500})
+      await expect(page).toHaveScreenshot(`TopicTag.${story.title}.xs.png`)
+
+      // Viewport: sm
+      await page.setViewportSize({width: viewports['primer.breakpoint.sm'], height: 500})
+      await expect(page).toHaveScreenshot(`TopicTag.${story.title}.sm.png`)
+
+      // Viewport: md
+      await page.setViewportSize({width: viewports['primer.breakpoint.md'], height: 500})
+      await expect(page).toHaveScreenshot(`TopicTag.${story.title}.md.png`)
+    })
+  })
+})

packages/postcss-preset-primer/src/mixins/buttonReset.css

@@ -0,0 +1,17 @@
+@define-mixin buttonReset {
+  margin: 0;
+  display: inline-flex;
+  padding: 0;
+  border: 0;
+  appearance: none;
+  background: none;
+  cursor: pointer;
+  text-align: start;
+  font: inherit;
+  color: inherit;
+  align-items: center;
+
+  &::-moz-focus-inner {
+    border: 0;
+  }
+}

packages/react/src/TopicTag/TopicTag.docs.json

@@ -0,0 +1,32 @@
+{
+  "id": "topic_tag",
+  "name": "TopicTag",
+  "status": "draft",
+  "a11yReviewed": false,
+  "stories": [],
+  "importPath": "@primer/react/experimental",
+  "props": [
+    {
+      "name": "as",
+      "type": "React.ElementType",
+      "description": "The HTML element or React component to render as the root element"
+    },
+    {
+      "name": "className",
+      "type": "string",
+      "description": "Provide a class name for styling on the outermost element"
+    }
+  ],
+  "subcomponents": [
+    {
+      "name": "TopicTag.Group",
+      "props": [
+        {
+          "name": "className",
+          "type": "string",
+          "description": "Provide a class name for styling on the outermost element"
+        }
+      ]
+    }
+  ]
+}

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

@@ -0,0 +1,35 @@
+import type {Meta} from '@storybook/react-vite'
+import {TopicTag} from './TopicTag'
+import {TopicTagGroup} from './TopicTagGroup'
+
+export default {
+  title: 'Experimental/Components/TopicTag/Features',
+  component: TopicTag,
+} satisfies Meta<typeof TopicTag>
+
+export const AsButton = () => <TopicTag as="button">react</TopicTag>
+
+export const AsGroup = () => {
+  const tags = [
+    'react',
+    'nodejs',
+    'javascript',
+    'd3',
+    'teachers',
+    'community',
+    'education',
+    'programming',
+    'curriculum',
+    'math',
+  ]
+
+  return (
+    <TopicTagGroup>
+      {tags.map(tag => (
+        <TopicTag key={tag} href={`/topics/${tag}`}>
+          {tag}
+        </TopicTag>
+      ))}
+    </TopicTagGroup>
+  )
+}

packages/react/src/TopicTag/TopicTag.module.css

@@ -0,0 +1,32 @@
+/* Add a reset for when TopicTag is an <a> element since our link styles apply an underline text-decoration by default */
+.TopicTag:where(a) {
+  text-decoration: none;
+}
+
+/* Add a reset for when TopicTag is a <button> element */
+.TopicTag:where(button) {
+  @mixin buttonReset;
+}
+
+.TopicTag {
+  background-color: var(--bgColor-accent-muted);
+  color: var(--fgColor-accent);
+  font-size: var(--text-body-size-small);
+  font-weight: var(--base-text-weight-semibold);
+  line-height: var(--text-body-lineHeight-small);
+  border-radius: var(--borderRadius-full);
+  padding: var(--base-size-2) var(--base-size-12);
+  border: var(--borderWidth-thin) solid var(--topicTag-borderColor, transparent);
+  display: inline-flex;
+  white-space: nowrap;
+
+  &:hover {
+    background-color: var(--bgColor-accent-emphasis);
+    color: var(--fgColor-onEmphasis);
+  }
+
+  &:where(a, button) {
+    cursor: pointer;
+    user-select: none;
+  }
+}

packages/react/src/TopicTag/TopicTag.stories.tsx

@@ -0,0 +1,13 @@
+import type {Meta, StoryObj} from '@storybook/react-vite'
+import {TopicTag} from './TopicTag'
+
+export default {
+  title: 'Experimental/Components/TopicTag',
+  component: TopicTag,
+} satisfies Meta<typeof TopicTag>
+
+export const Default = () => <TopicTag>react</TopicTag>
+
+export const Playground: StoryObj<typeof TopicTag> = {
+  render: args => <TopicTag {...args}>react</TopicTag>,
+}

packages/react/src/TopicTag/TopicTag.test.tsx

@@ -0,0 +1,39 @@
+import {render, screen} from '@testing-library/react'
+import {describe, test, expect, vi} from 'vitest'
+import {userEvent} from 'vitest/browser'
+import {TopicTag} from '../TopicTag'
+
+describe('TopicTag', () => {
+  test('defaults to <a> semantics', async () => {
+    render(<TopicTag href="#">test</TopicTag>)
+
+    expect(screen.getByRole('link', {name: 'test'})).toBeInTheDocument()
+  })
+
+  test('support <button> semantics through `as` prop', async () => {
+    const onClick = vi.fn()
+    render(
+      <TopicTag as="button" onClick={onClick}>
+        test
+      </TopicTag>,
+    )
+
+    await userEvent.click(screen.getByRole('button', {name: 'test'}))
+    expect(onClick).toHaveBeenCalled()
+  })
+
+  test('supports `className` merging', () => {
+    const {container} = render(<TopicTag className="custom-class">test</TopicTag>)
+    expect(container.firstChild).toHaveClass('custom-class')
+  })
+
+  test('additional props are applied to outermost element', () => {
+    const {container} = render(
+      <TopicTag data-testid="test" id="test-id">
+        test
+      </TopicTag>,
+    )
+    expect(container.firstChild).toHaveAttribute('data-testid', 'test')
+    expect(container.firstChild).toHaveAttribute('id', 'test-id')
+  })
+})

packages/react/src/TopicTag/TopicTag.tsx

@@ -0,0 +1,27 @@
+import {clsx} from 'clsx'
+import type {ElementType} from 'react'
+import classes from './TopicTag.module.css'
+
+type TopicTagProps<As extends ElementType> = {
+  /**
+   * The HTML element or React component to render as the root element
+   */
+  as?: As
+
+  /**
+   * Provide a class name for styling on the outermost element
+   */
+  className?: string
+} & Omit<React.ComponentPropsWithoutRef<As>, 'as' | 'className'>
+
+function TopicTag<As extends ElementType = 'a'>({as, children, className, ...rest}: TopicTagProps<As>) {
+  const BaseComponent = as ?? 'a'
+  return (
+    <BaseComponent {...rest} className={clsx(className, classes.TopicTag)}>
+      {children}
+    </BaseComponent>
+  )
+}
+
+export {TopicTag}
+export type {TopicTagProps}

packages/react/src/TopicTag/TopicTagGroup.module.css

@@ -0,0 +1,6 @@
+.TopicTagGroup {
+  display: flex;
+  flex-wrap: wrap;
+  column-gap: var(--base-size-2);
+  row-gap: var(--base-size-8);
+}

packages/react/src/TopicTag/TopicTagGroup.test.tsx

@@ -0,0 +1,20 @@
+import {render} from '@testing-library/react'
+import {describe, test, expect} from 'vitest'
+import {TopicTagGroup} from './TopicTagGroup'
+
+describe('TopicTagGroup', () => {
+  test('supports `className` merging', () => {
+    const {container} = render(<TopicTagGroup className="custom-class">test</TopicTagGroup>)
+    expect(container.firstChild).toHaveClass('custom-class')
+  })
+
+  test('additional props are applied to outermost element', () => {
+    const {container} = render(
+      <TopicTagGroup data-testid="test" id="test-id">
+        test
+      </TopicTagGroup>,
+    )
+    expect(container.firstChild).toHaveAttribute('data-testid', 'test')
+    expect(container.firstChild).toHaveAttribute('id', 'test-id')
+  })
+})

packages/react/src/TopicTag/TopicTagGroup.tsx

@@ -0,0 +1,16 @@
+import {clsx} from 'clsx'
+import type React from 'react'
+import classes from './TopicTagGroup.module.css'
+
+type TopicTagGroupProps = React.HTMLAttributes<HTMLElement>
+
+function TopicTagGroup({children, className, ...rest}: TopicTagGroupProps) {
+  return (
+    <div {...rest} className={clsx(className, classes.TopicTagGroup)}>
+      {children}
+    </div>
+  )
+}
+
+export {TopicTagGroup}
+export type {TopicTagGroupProps}

packages/react/src/TopicTag/index.ts

@@ -0,0 +1,11 @@
+import {TopicTag as TopicTagImpl} from './TopicTag'
+import type {TopicTagProps} from './TopicTag'
+import {TopicTagGroup} from './TopicTagGroup'
+import type {TopicTagGroupProps} from './TopicTagGroup'
+
+const TopicTag = Object.assign(TopicTagImpl, {
+  Group: TopicTagGroup,
+})
+
+export {TopicTag}
+export type {TopicTagProps, TopicTagGroupProps}

packages/react/src/__tests__/__snapshots__/exports.test.ts.snap

@@ -356,6 +356,9 @@ exports[`@primer/react/experimental > should not update exports without a semver
   "type TitleProps",
   "Tooltip",
   "type TooltipProps",
+  "TopicTag",
+  "type TopicTagGroupProps",
+  "type TopicTagProps",
   "UnderlinePanels",
   "type UnderlinePanelsPanelProps",
   "type UnderlinePanelsProps",

packages/react/src/experimental/index.ts

@@ -94,3 +94,6 @@ export type {IssueLabelProps} from './IssueLabel'
 
 export * from '../KeybindingHint'
 export * from './Tabs'
+
+export {TopicTag} from '../TopicTag'
+export type {TopicTagProps, TopicTagGroupProps} from '../TopicTag'