Add heading component

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openstax/ui-components",
-  "version": "1.23.1",
+  "version": "1.23.2",
   "license": "MIT",
   "sideEffects": [
     "**/*.css"

src/components/Text.spec.tsx

@@ -1,5 +1,7 @@
-import { Paragraph, H2, H3 } from './Text';
+import { Paragraph, H2, H3, Heading } from './Text';
 import renderer from 'react-test-renderer';
+import { render } from '@testing-library/react';
+import React from 'react';
 
 describe('Text', () => {
   it('matches body snapshot', () => {
@@ -24,3 +26,41 @@ describe('Text', () => {
   });
 
 });
+
+describe('Heading', () => {
+  it('defaults variant to match the semantic level', () => {
+    const tree = renderer.create(
+      <Heading level={2}>This is a heading</Heading>
+    ).toJSON();
+    expect(tree).toMatchObject({ type: 'h2', props: { className: 'text-h2' } });
+  });
+
+  it('renders the element for the given level', () => {
+    const tree = renderer.create(
+      <Heading level={4}>This is a heading</Heading>
+    ).toJSON();
+    expect((tree as unknown as { type: string }).type).toBe('h4');
+  });
+
+  it('decouples visual style from semantic level', () => {
+    // an <h2> element styled like an h3
+    const tree = renderer.create(
+      <Heading level={2} variant="h3">This is a heading</Heading>
+    ).toJSON();
+    expect(tree).toMatchObject({ type: 'h2', props: { className: 'text-h3' } });
+  });
+
+  it('merges a consumer className with the variant class', () => {
+    const tree = renderer.create(
+      <Heading level={2} className="custom">This is a heading</Heading>
+    ).toJSON();
+    expect((tree as unknown as { props: { className: string } }).props.className).toBe('text-h2 custom');
+  });
+
+  it('forwards a ref to the underlying element', () => {
+    const ref = React.createRef<HTMLHeadingElement>();
+    render(<Heading level={2} ref={ref}>This is a heading</Heading>);
+    expect(ref.current).not.toBeNull();
+    expect(ref.current?.tagName).toBe('H2');
+  });
+});

src/components/Text.stories.tsx

@@ -1,4 +1,4 @@
-import { H2, H3, Paragraph } from "./Text";
+import { H2, H3, Heading as HeadingComponent, Paragraph } from "./Text";
 
 export const PText = () => (
   <>
@@ -12,3 +12,11 @@ export const Heading = () => (
     <H3>H3 Heading text</H3>
   </>
 );
+
+// Semantic level and visual style are independent: this renders an <h2>
+// element (correct document outline) styled like an h3.
+export const HeadingStyleOverride = () => (
+  <HeadingComponent level={2} variant="h3">
+    h2 element with h3 style
+  </HeadingComponent>
+);

src/components/Text.tsx

@@ -2,18 +2,46 @@ import React from 'react';
 import classNames from 'classnames';
 import './Text.css';
 
+export type HeadingLevel = 1 | 2 | 3 | 4 | 5 | 6;
+
+/**
+ * Visual style applied to a heading, decoupled from its semantic level.
+ * Maps to the `text-*` classes in Text.css.
+ */
+export type HeadingVariant = 'h2' | 'h3';
+
+export interface HeadingProps extends React.ComponentPropsWithoutRef<'h2'> {
+  /** Semantic heading level — controls which `h1`–`h6` element is rendered. */
+  level: HeadingLevel;
+  /** Visual style to apply. Defaults to match `level` (e.g. `level={2}` → `h2`). */
+  variant?: HeadingVariant;
+}
+
+/**
+ * Renders a heading whose semantic level (the rendered `h1`–`h6` tag) is
+ * independent of its visual style (`variant`). This lets consumers preserve a
+ * correct document outline while reusing an existing heading style — e.g.
+ * `<Heading level={2} variant="h3">` is an `<h2>` styled like an h3.
+ */
+export const Heading = React.forwardRef<HTMLHeadingElement, HeadingProps>(
+  ({ level, variant, className, ...props }, ref) => {
+    const Tag = `h${level}` as const;
+    // Default the visual style to match the semantic level.
+    const resolvedVariant = variant ?? (`h${level}` as HeadingVariant);
+    return <Tag ref={ref} className={classNames(`text-${resolvedVariant}`, className)} {...props} />;
+  }
+);
+
+Heading.displayName = 'Heading';
+
 export const H2 = React.forwardRef<HTMLHeadingElement, React.ComponentPropsWithoutRef<'h2'>>(
-  ({ className, ...props }, ref) => (
-    <h2 ref={ref} className={classNames('text-h2', className)} {...props} />
-  )
+  (props, ref) => <Heading level={2} ref={ref} {...props} />
 );
 
 H2.displayName = 'H2';
 
 export const H3 = React.forwardRef<HTMLHeadingElement, React.ComponentPropsWithoutRef<'h3'>>(
-  ({ className, ...props }, ref) => (
-    <h3 ref={ref} className={classNames('text-h3', className)} {...props} />
-  )
+  (props, ref) => <Heading level={3} ref={ref} {...props} />
 );
 
 H3.displayName = 'H3';