Clearly distinguish between CSS and Emotion CSS

.changeset/unpopular-aduls-behave.md

@@ -0,0 +1,7 @@
+---
+'@guardian/source-foundations': major
+---
+
+- The `input` reset now returns a `SerializedStyles` Emotion object instead of a `string`
+- Typography functions: `headline`, `textSans`, `body`, and `titlepiece` now return a `SerializedStyles` Emotion object instead of a `string`.
+  - String alternatives are provided, but please note that link underline hover styles won't work as expected unless added separately, because they depend on the parent selector which is only available in Emotion.

packages/@guardian/source-foundations/src/index.test.ts

@@ -32,6 +32,7 @@ it('Should have exactly these exports', () => {
 		'body',
 		'bodyObjectStyles',
 		'bodySizes',
+		'bodyString',
 		'border',
 		'brand',
 		'brandAlt',
@@ -57,6 +58,7 @@ it('Should have exactly these exports', () => {
 		'headline',
 		'headlineObjectStyles',
 		'headlineSizes',
+		'headlineString',
 		'height',
 		'iconSize',
 		'labs',
@@ -87,9 +89,11 @@ it('Should have exactly these exports', () => {
 		'textSans',
 		'textSansObjectStyles',
 		'textSansSizes',
+		'textSansString',
 		'titlepiece',
 		'titlepieceObjectStyles',
 		'titlepieceSizes',
+		'titlepieceString',
 		'transitions',
 		'until',
 		'visuallyHidden',

packages/@guardian/source-foundations/src/index.ts

@@ -71,6 +71,10 @@ export {
 	headline,
 	body,
 	textSans,
+	titlepieceString,
+	headlineString,
+	bodyString,
+	textSansString,
 	titlepieceSizes,
 	headlineSizes,
 	bodySizes,

packages/@guardian/source-foundations/src/typography/font-styles.ts

@@ -1,3 +1,4 @@
+import { css } from '@emotion/react';
 import {
 	availableFontWeights,
 	fonts,
@@ -12,6 +13,8 @@ import type {
 	Categories,
 	FontScaleArgs,
 	FontScaleFunction,
+	FontScaleFunctionEmotion,
+	FontScaleFunctionStr,
 	FontStyle,
 	Option,
 	TypographyConfiguration,
@@ -103,37 +106,53 @@ export const fontStyleFunction =
 		};
 	};
 
+/**
+ * Helper method that returns a valid CSS string for a given set of typography styles.
+ */
+const fontStyleToCssString = (styles: TypographyStyles) => {
+	const { fontFamily, fontSize, fontStyle, fontWeight, lineHeight } = styles;
+
+	return `
+		font-family: ${fontFamily};
+		font-size: ${typeof fontSize === 'number' ? `${fontSize}px` : fontSize};
+		line-height: ${lineHeight};
+		${fontWeight ? `font-weight: ${fontWeight};` : ''}
+		${fontStyle ? `font-style: ${fontStyle};` : ''}
+	`;
+};
+
 /**
  * Generates a method that evaluates a given font scale function with the
  * provided options and returns the typography styles as a CSS string.
  *
+ * This method will not work with the `textDecorationThickness` property.
+ * If you require this, please use `fontStyleToEmotionFunction` instead.
+ *
  * For an example usage see our {@link [typography string function exports](./index.ts)}.
  */
 export const fontStyleToStringFunction =
-	(typographyFunction: FontScaleFunction) =>
-	(options?: FontScaleArgs): string => {
-		const {
-			fontFamily,
-			fontSize,
-			fontStyle,
-			fontWeight,
-			lineHeight,
-			textDecorationThickness,
-		} = typographyFunction(options);
+	(typographyFunction: FontScaleFunction): FontScaleFunctionStr =>
+	(options?: FontScaleArgs) =>
+		fontStyleToCssString(typographyFunction(options));
 
-		return `
-			font-family: ${fontFamily};
-			font-size: ${typeof fontSize === 'number' ? `${fontSize}px` : fontSize};
-			line-height: ${lineHeight};
-			${fontWeight ? `font-weight: ${fontWeight}` : ''};
-			${fontStyle ? `font-style: ${fontStyle}` : ''};
+/**
+ * Generates a method that evaluates a given font scale function with the
+ * provided options and returns the typography styles as a serialised emotion object.
+ *
+ * For an example usage see our {@link [typography string function exports](./index.ts)}.
+ */
+export const fontStyleToEmotionFunction =
+	(typographyFunction: FontScaleFunction): FontScaleFunctionEmotion =>
+	(options?: FontScaleArgs) => {
+		const { textDecorationThickness, ...fontStyles } =
+			typographyFunction(options);
 
+		return css`
+			${fontStyleToCssString(fontStyles)}
 			&:hover {
-				${
-					textDecorationThickness
-						? `text-decoration-thickness: ${textDecorationThickness}px`
-						: ``
-				};
+				${textDecorationThickness
+					? `text-decoration-thickness: ${textDecorationThickness}px;`
+					: ``}
 			}
 		`;
 	};

packages/@guardian/source-foundations/src/typography/index.ts

@@ -4,12 +4,16 @@ import {
 	textSans as textSansAsObj,
 	titlepiece as titlepieceAsObj,
 } from './api';
-import { fontStyleToStringFunction } from './font-styles';
+import {
+	fontStyleToEmotionFunction,
+	fontStyleToStringFunction,
+} from './font-styles';
 import type {
 	BodySizes,
 	HeadlineSizes,
 	TextSansSizes,
 	TitlepieceSizes,
+	TypographyEmotionFunctions,
 	TypographyStrFunctions,
 } from './types';
 
@@ -21,7 +25,13 @@ import type {
  * font-family: 'GT Guardian Titlepiece';
  * ```
  */
-export const titlepiece: TypographyStrFunctions<TitlepieceSizes> = {
+export const titlepiece: TypographyEmotionFunctions<TitlepieceSizes> = {
+	small: fontStyleToEmotionFunction(titlepieceAsObj.small),
+	medium: fontStyleToEmotionFunction(titlepieceAsObj.medium),
+	large: fontStyleToEmotionFunction(titlepieceAsObj.large),
+};
+
+export const titlepieceString: TypographyStrFunctions<TitlepieceSizes> = {
 	small: fontStyleToStringFunction(titlepieceAsObj.small),
 	medium: fontStyleToStringFunction(titlepieceAsObj.medium),
 	large: fontStyleToStringFunction(titlepieceAsObj.large),
@@ -35,7 +45,17 @@ export const titlepiece: TypographyStrFunctions<TitlepieceSizes> = {
  * font-family: 'GH Guardian Headline';
  * ```
  */
-export const headline: TypographyStrFunctions<HeadlineSizes> = {
+export const headline: TypographyEmotionFunctions<HeadlineSizes> = {
+	xxxsmall: fontStyleToEmotionFunction(headlineAsObj.xxxsmall),
+	xxsmall: fontStyleToEmotionFunction(headlineAsObj.xxsmall),
+	xsmall: fontStyleToEmotionFunction(headlineAsObj.xsmall),
+	small: fontStyleToEmotionFunction(headlineAsObj.small),
+	medium: fontStyleToEmotionFunction(headlineAsObj.medium),
+	large: fontStyleToEmotionFunction(headlineAsObj.large),
+	xlarge: fontStyleToEmotionFunction(headlineAsObj.xlarge),
+};
+
+export const headlineString: TypographyStrFunctions<HeadlineSizes> = {
 	xxxsmall: fontStyleToStringFunction(headlineAsObj.xxxsmall),
 	xxsmall: fontStyleToStringFunction(headlineAsObj.xxsmall),
 	xsmall: fontStyleToStringFunction(headlineAsObj.xsmall),
@@ -53,7 +73,13 @@ export const headline: TypographyStrFunctions<HeadlineSizes> = {
  * font-family: 'GuardianTextEgyptian';
  * ```
  */
-export const body: TypographyStrFunctions<BodySizes> = {
+export const body: TypographyEmotionFunctions<BodySizes> = {
+	xsmall: fontStyleToEmotionFunction(bodyAsObj.xsmall),
+	small: fontStyleToEmotionFunction(bodyAsObj.small),
+	medium: fontStyleToEmotionFunction(bodyAsObj.medium),
+};
+
+export const bodyString: TypographyStrFunctions<BodySizes> = {
 	xsmall: fontStyleToStringFunction(bodyAsObj.xsmall),
 	small: fontStyleToStringFunction(bodyAsObj.small),
 	medium: fontStyleToStringFunction(bodyAsObj.medium),
@@ -67,7 +93,18 @@ export const body: TypographyStrFunctions<BodySizes> = {
  * font-family: 'GuardianTextSans';
  * ```
  */
-export const textSans: TypographyStrFunctions<TextSansSizes> = {
+export const textSans: TypographyEmotionFunctions<TextSansSizes> = {
+	xxsmall: fontStyleToEmotionFunction(textSansAsObj.xxsmall),
+	xsmall: fontStyleToEmotionFunction(textSansAsObj.xsmall),
+	small: fontStyleToEmotionFunction(textSansAsObj.small),
+	medium: fontStyleToEmotionFunction(textSansAsObj.medium),
+	large: fontStyleToEmotionFunction(textSansAsObj.large),
+	xlarge: fontStyleToEmotionFunction(textSansAsObj.xlarge),
+	xxlarge: fontStyleToEmotionFunction(textSansAsObj.xxlarge),
+	xxxlarge: fontStyleToEmotionFunction(textSansAsObj.xxxlarge),
+};
+
+export const textSansString: TypographyStrFunctions<TextSansSizes> = {
 	xxsmall: fontStyleToStringFunction(textSansAsObj.xxsmall),
 	xsmall: fontStyleToStringFunction(textSansAsObj.xsmall),
 	small: fontStyleToStringFunction(textSansAsObj.small),

packages/@guardian/source-foundations/src/typography/types.ts

@@ -1,3 +1,4 @@
+import type { SerializedStyles } from '@emotion/react';
 import type {
 	bodySizes,
 	fontWeights,
@@ -78,11 +79,19 @@ export type FontScaleFunction = (options?: FontScaleArgs) => TypographyStyles;
 
 // returns styles as a template literal
 export type FontScaleFunctionStr = (options?: FontScaleArgs) => string;
+// returns styles as an Emotion SerializedStyles object
+export type FontScaleFunctionEmotion = (
+	options?: FontScaleArgs,
+) => SerializedStyles;
 
 export type TypographyStrFunctions<Sizes extends AvailableSizes> = {
 	[key in keyof Sizes]: FontScaleFunctionStr;
 };
 
+export type TypographyEmotionFunctions<Sizes extends AvailableSizes> = {
+	[key in keyof Sizes]: FontScaleFunctionEmotion;
+};
+
 export type TypographyFunctions<Sizes extends AvailableSizes> = {
 	[key in keyof Sizes]: FontScaleFunction;
 };