feat(typography): add new next component

src/components/typography/__next__/config.ts

@@ -0,0 +1,116 @@
+import { CSSProperties } from "react";
+import { ArgTypes } from "@storybook/react";
+
+const VARIANT_TYPES = [
+  "h1",
+  "h2",
+  "h3",
+  "h4",
+  "h5",
+  "section-header",
+  "section-subheader",
+  "p",
+] as const;
+
+const VALID_HTML_VARIANTS = ["h1", "h2", "h3", "h4", "h5", "p"] as const;
+
+type VariantTypes = (typeof VARIANT_TYPES)[number];
+type ValidHtmlVariant = (typeof VALID_HTML_VARIANTS)[number];
+
+const VARIANT_TYPES_ARG_TYPES: ArgTypes = {
+  variant: {
+    options: VARIANT_TYPES,
+    control: {
+      type: "select",
+    },
+  },
+  as: {
+    options: VALID_HTML_VARIANTS,
+    control: {
+      type: "select",
+    },
+  },
+  fluid: {
+    control: "boolean",
+  },
+  inverse: {
+    control: "boolean",
+  },
+  screenReaderOnly: {
+    control: "boolean",
+  },
+  size: {
+    options: ["regular", "large"],
+    control: {
+      type: "select",
+    },
+  },
+  tint: {
+    options: ["default", "alt"],
+    control: {
+      type: "select",
+    },
+  },
+  weight: {
+    options: ["regular", "medium"],
+    control: {
+      type: "select",
+    },
+  },
+};
+
+const ALLOWED_CSS_TEXT_OVERRIDE_KEYS = [
+  "textTransform",
+  "textDecoration",
+  "display",
+  "whiteSpace",
+  "wordBreak",
+  "wordWrap",
+  "textAlign",
+  "textOverflow",
+  "overflow",
+] as const satisfies (keyof CSSProperties)[];
+
+type AllowedCSSTextOverrides = Pick<
+  CSSProperties,
+  (typeof ALLOWED_CSS_TEXT_OVERRIDE_KEYS)[number]
+>;
+
+const ALLOWED_CSS_TEXT_OVERRIDES_ARG_TYPES: ArgTypes = {
+  color: {
+    control: "text",
+    description: "CSS color value for text",
+  },
+  fontSize: {
+    control: "text",
+    description: "CSS font-size value",
+  },
+  fontWeight: {
+    control: "text",
+    description: "CSS font-weight value",
+  },
+  letterSpacing: {
+    control: "text",
+    description: "CSS letter-spacing value",
+  },
+  lineHeight: {
+    control: "text",
+    description: "CSS line-height value",
+  },
+  textDecoration: {
+    control: "text",
+    description: "CSS text-decoration value",
+  },
+  textTransform: {
+    control: "text",
+    description: "CSS text-transform value",
+  },
+};
+
+export {
+  VARIANT_TYPES,
+  VARIANT_TYPES_ARG_TYPES,
+  ALLOWED_CSS_TEXT_OVERRIDE_KEYS,
+  ALLOWED_CSS_TEXT_OVERRIDES_ARG_TYPES,
+};
+export type { VariantTypes, ValidHtmlVariant, AllowedCSSTextOverrides };

src/components/typography/__next__/index.ts

@@ -0,0 +1,2 @@
+export { default } from "./typography.component";
+export type { TypographyProps } from "./typography.component";

src/components/typography/__next__/typography-test.stories.tsx

@@ -0,0 +1,35 @@
+import React from "react";
+import Typography, { TypographyProps } from ".";
+import generateStyledSystemProps from "../../../../.storybook/utils/styled-system-props";
+import {
+  VARIANT_TYPES_ARG_TYPES,
+  ALLOWED_CSS_TEXT_OVERRIDES_ARG_TYPES,
+} from "./config";
+
+const styledSystemProps = generateStyledSystemProps({
+  spacing: true,
+});
+
+export default {
+  title: "Typography/Test",
+  component: Typography,
+  parameters: {
+    info: { disable: true },
+    chromatic: {
+      disableSnapshot: true,
+    },
+  },
+  argTypes: {
+    ...VARIANT_TYPES_ARG_TYPES,
+    ...ALLOWED_CSS_TEXT_OVERRIDES_ARG_TYPES,
+    ...styledSystemProps,
+  },
+};
+
+export const Default = ({ children, ...args }: TypographyProps) => {
+  return <Typography {...args}>{children}</Typography>;
+};
+Default.storyName = "default";
+Default.args = {
+  children: "Typography",
+};

src/components/typography/__next__/typography.component.tsx

@@ -0,0 +1,92 @@
+import React from "react";
+import { SpaceProps } from "styled-system";
+import tagComponent, {
+  TagProps,
+} from "../../../__internal__/utils/helpers/tags";
+import {
+  filterStyledSystemMarginProps,
+  filterStyledSystemPaddingProps,
+} from "../../../style/utils";
+import StyledTypography from "./typography.style";
+import filterObjectProperties from "../../../__internal__/filter-object-properties";
+import {
+  VariantTypes,
+  ValidHtmlVariant,
+  ALLOWED_CSS_TEXT_OVERRIDE_KEYS,
+  AllowedCSSTextOverrides,
+} from "./config";
+
+export interface TypographyProps
+  extends SpaceProps,
+    TagProps,
+    AllowedCSSTextOverrides {
+  /** Adds element and creates a visual style associated with said element. */
+  variant?: VariantTypes;
+  /** Override the underlying HTML element rendered by the component. */
+  as?: ValidHtmlVariant;
+  /** Content to be rendered inside the Typography component. */
+  children?: React.ReactNode;
+  /** Set the ID attribute of the Typography component. */
+  id?: string;
+  /** When set to `true`, uses fluid typography with CSS clamp() values for responsive sizing. */
+  fluid?: boolean;
+  /** When set to `true`, inverts the font color for use on darker backgrounds. */
+  inverse?: boolean;
+  /** When set to `true`, the component will apply visually hidden styling, hiding the component visually but ensuring the component is still in the accessibility tree. */
+  screenReaderOnly?: boolean;
+  /** The size to apply to paragraph text. Only available when variant is "p". */
+  size?: "regular" | "large";
+  /** The color tint to apply to paragraph text. Accepts "default" for standard text color or "alt" for alternative text color. Only available when variant is "p". */
+  tint?: "default" | "alt";
+  /** The font weight to apply to paragraph text. Only available when variant is "p". */
+  weight?: "regular" | "medium";
+}
+
+export const Typography = ({
+  variant = "p",
+  as,
+  children,
+  id,
+  fluid = false,
+  inverse,
+  screenReaderOnly,
+  size = "regular",
+  tint = "default",
+  weight = "regular",
+  ...rest
+}: TypographyProps) => {
+  function calculateAs() {
+    if (as) {
+      return as;
+    }
+    if (variant === "section-header") {
+      return "h2";
+    }
+    if (variant === "section-subheader") {
+      return "h3";
+    }
+    return variant;
+  }
+
+  return (
+    <StyledTypography
+      id={id}
+      as={calculateAs()}
+      variant={variant}
+      fluid={fluid}
+      inverse={inverse}
+      screenReaderOnly={screenReaderOnly}
+      size={size}
+      tint={tint}
+      weight={weight}
+      {...tagComponent("typography", rest)}
+      {...filterStyledSystemMarginProps(rest)}
+      {...filterStyledSystemPaddingProps(rest)}
+      {...filterObjectProperties(rest, ALLOWED_CSS_TEXT_OVERRIDE_KEYS)}
+    >
+      {children}
+    </StyledTypography>
+  );
+};
+
+export default Typography;

src/components/typography/__next__/typography.mdx

@@ -0,0 +1,85 @@
+import { Meta, ArgTypes, Canvas } from "@storybook/blocks";
+
+import * as TypographyStories from "./typography.stories.tsx";
+
+<Meta of={TypographyStories} />
+
+# Typography
+
+<a
+  target="_blank"
+  href="https://zeroheight.com/35ee2cc26/v/latest/p/29b3b7-typography"
+  style={{ color: "#007E45", fontWeight: "bold", textDecoration: "underline" }}
+  rel="noreferrer"
+>
+  Product Design System component
+</a>
+
+Manages text styles and content hierarchies.
+
+## Contents
+
+- [Quick Start](#quick-start)
+- [Examples](#examples)
+- [Props](#props)
+
+## Quick Start
+
+```javascript
+import Typography from "carbon-react/lib/components/typography/__next__/";
+```
+
+## Designer Notes
+
+- The Typography component provides a consistent and flexible system for managing text styles across your design. 
+- It includes multiple heading and body text options to accommodate various content hierarchies.
+- With theme support for large screens and small screens, this helps ensure readability and brand alignment across different contexts. 
+
+## Examples
+
+### Variants
+
+Use the `variant` prop to render an element and creates a visual style associated with said element. The `as` prop can also be 
+used to override the underlying HTML element.
+
+<Canvas of={TypographyStories.VariantsStory} />
+
+
+## Fluid
+
+When set to `true`, the component uses fluid typography with CSS clamp() values for responsive sizing. 
+This allows the text to scale smoothly between breakpoints without requiring media queries.
+
+<Canvas of={TypographyStories.FluidStory} />
+
+## Inverse
+
+When set to `true`, inverts the font colour for use on darker backgrounds. 
+This ensures sufficient contrast and readability when the Typography component is placed over dark container backgrounds.
+
+<Canvas of={TypographyStories.InverseStory} />
+
+## Size
+
+The `size` prop controls the font size applied to paragraph text. 
+Only available when `variant` is set to `"p"`. Choose between `"regular"` for standard text and `"large"` for emphasis.
+
+<Canvas of={TypographyStories.SizeStory} />
+
+## Tint
+
+The `tint` prop applies a colour tint to paragraph text. 
+Only available when `variant` is set to `"p"`. Use `"default"` for standard text colour or `"alt"` for alternative text colour.
+
+<Canvas of={TypographyStories.TintStory} />
+
+## Weight
+
+The `weight` prop controls the font weight applied to paragraph text. 
+Only available when `variant` is set to `"p"`. Choose between `"regular"` for normal weight or `"medium"` for heavier emphasis.
+
+<Canvas of={TypographyStories.WeightStory} />
+
+## Props
+
+<ArgTypes of={TypographyStories} />