Deprecate typography API

libs/@guardian/source-foundations/src/typography/data.ts → libs/@guardian/source-foundations/src/_deprecated/typography/data.ts

@@ -3,14 +3,16 @@ import {
 	fontArrayToString,
 	pxStringToNumber,
 	pxToRem,
-} from '../utils/convert-value';
+} from '../../utils/convert-value';
 import type { AvailableFontWeights, ItalicsFontWeights } from './types';
 
 /**
  * Pixel size values for each font that we use in the design system.
  *
  * We assert that the values match the guardian type scale in our
  * {@link [unit test suite](./typography.test.ts)}.
+ *
+ * @deprecated Please typography presets rather than setting individual values
  */
 export const pxTextSizes = {
 	textSans: {
@@ -52,6 +54,8 @@ export const pxTextSizes = {
  * in our {@link [unit test suite](./typography.test.ts)}.
  *
  * See {@link [pxToRem](../utils/convert-value.ts)} for more details.
+ *
+ * @deprecated Please typography presets rather than setting individual values
  */
 export const remTextSizes = {
 	textSans: {
@@ -85,6 +89,9 @@ export const remTextSizes = {
 	},
 } as const;
 
+/**
+ * @deprecated Please typography presets rather than setting individual values
+ */
 export const fonts = {
 	titlepiece: fontArrayToString(tokens.typography.fontFamily.titlepiece),
 	headline: fontArrayToString(tokens.typography.fontFamily.headline),
@@ -104,34 +111,40 @@ export const fonts = {
  * can be overridden by users.
  *
  * @see https://www.w3.org/WAI/WCAG21/Understanding/text-spacing
+ *
+ * @deprecated Please typography presets rather than setting individual values
  */
 export const lineHeights = {
 	tight: tokens.typography.lineHeight.tight,
 	regular: tokens.typography.lineHeight.regular,
 	loose: tokens.typography.lineHeight.loose,
 } as const;
 
+/** @deprecated Please typography presets rather than setting individual values */
 export const fontWeights = {
 	light: tokens.typography.fontWeight.light,
 	regular: tokens.typography.fontWeight.regular,
 	medium: tokens.typography.fontWeight.medium,
 	bold: tokens.typography.fontWeight.bold,
 } as const;
 
+/** @deprecated Please typography presets rather than setting individual values */
 export const availableFontWeights = {
 	titlepiece: { bold: true },
 	headline: { light: true, medium: true, bold: true },
 	body: { regular: true, bold: true },
 	textSans: { regular: true, bold: true },
 } as AvailableFontWeights;
 
+/** @deprecated Please typography presets rather than setting individual values */
 export const italicsFontWeights = {
 	titlepiece: { bold: false },
 	headline: { light: true, medium: true, bold: false },
 	body: { regular: true, bold: true },
 	textSans: { regular: true, bold: false },
 } as ItalicsFontWeights;
 
+/** @deprecated Please typography presets rather than setting individual values */
 export const underlineThickness = {
 	textSans: {
 		xxsmall: pxStringToNumber(
@@ -207,19 +220,29 @@ export const underlineThickness = {
 } as const;
 
 // Pixel font size exports
+
+/** @deprecated Please typography presets rather than setting individual values */
 export const textSansSizes = pxTextSizes.textSans;
 
+/** @deprecated Please typography presets rather than setting individual values */
 export const bodySizes = pxTextSizes.body;
 
+/** @deprecated Please typography presets rather than setting individual values */
 export const headlineSizes = pxTextSizes.headline;
 
+/** @deprecated Please typography presets rather than setting individual values */
 export const titlepieceSizes = pxTextSizes.titlepiece;
 
 // Computed rem font size exports
+
+/** @deprecated Please typography presets rather than setting individual values */
 export const remBodySizes = remTextSizes.body;
 
+/** @deprecated Please typography presets rather than setting individual values */
 export const remTitlepieceSizes = remTextSizes.titlepiece;
 
+/** @deprecated Please typography presets rather than setting individual values */
 export const remHeadlineSizes = remTextSizes.headline;
 
+/** @deprecated Please typography presets rather than setting individual values */
 export const remTextSansSizes = remTextSizes.textSans;

libs/@guardian/source-foundations/src/typography/index.ts → libs/@guardian/source-foundations/src/_deprecated/typography/index.ts

@@ -20,6 +20,8 @@ import type {
  * ```
  * font-family: 'GT Guardian Titlepiece';
  * ```
+ *
+ * @deprecated Web typography presets should be used instead
  */
 export const titlepiece: TypographyStrFunctions<TitlepieceSizes> = {
 	small: fontStyleToStringFunction(titlepieceAsObj.small),
@@ -34,6 +36,8 @@ export const titlepiece: TypographyStrFunctions<TitlepieceSizes> = {
  * ```
  * font-family: 'GH Guardian Headline';
  * ```
+ *
+ * @deprecated Web typography presets should be used instead
  */
 export const headline: TypographyStrFunctions<HeadlineSizes> = {
 	xxxsmall: fontStyleToStringFunction(headlineAsObj.xxxsmall),
@@ -52,6 +56,8 @@ export const headline: TypographyStrFunctions<HeadlineSizes> = {
  * ```
  * font-family: 'GuardianTextEgyptian';
  * ```
+ *
+ * @deprecated Web typography presets should be used instead
  */
 export const body: TypographyStrFunctions<BodySizes> = {
 	xsmall: fontStyleToStringFunction(bodyAsObj.xsmall),
@@ -66,6 +72,8 @@ export const body: TypographyStrFunctions<BodySizes> = {
  * ```
  * font-family: 'GuardianTextSans';
  * ```
+ *
+ * @deprecated Web typography presets should be used instead
  */
 export const textSans: TypographyStrFunctions<TextSansSizes> = {
 	xxsmall: fontStyleToStringFunction(textSansAsObj.xxsmall),

libs/@guardian/source-foundations/src/typography/storybookTypographyRenderers.tsx → libs/@guardian/source-foundations/src/_deprecated/typography/storybookTypographyRenderers.tsx

@@ -1,9 +1,9 @@
+import { fontWeights } from '.';
 import {
-	bodyObjectStyles,
-	fontWeights,
-	headlineObjectStyles,
-	textSansObjectStyles,
-} from '../index';
+	body as bodyObjectStyles,
+	headline as headlineObjectStyles,
+	textSans as textSansObjectStyles,
+} from './obj';
 import type { Category, FontScaleFunction, FontWeight } from './types';
 
 type FontFunctions = {

libs/@guardian/source-foundations/src/_deprecated/typography/types.ts

@@ -1,4 +1,139 @@
-/** @deprecated TypographySizes will be removed in a future major release */
+import type {
+	bodySizes,
+	fontWeights,
+	headlineSizes,
+	lineHeights,
+	remBodySizes,
+	remHeadlineSizes,
+	remTextSansSizes,
+	remTitlepieceSizes,
+	textSansSizes,
+	titlepieceSizes,
+} from './data';
+
+/** @deprecated This type will be removed in a future major release */
+export type ScaleUnit = 'rem' | 'px';
+/** @deprecated This type will be removed in a future major release */
+export type LineHeight = keyof typeof lineHeights;
+/** @deprecated This type will be removed in a future major release */
+export type FontWeight = 'light' | 'regular' | 'medium' | 'bold';
+/** @deprecated This type will be removed in a future major release */
+export type FontStyle = 'normal' | 'italic';
+/** @deprecated This type will be removed in a future major release */
+export type FontWeightDefinition = { hasItalic: boolean };
+/** @deprecated This type will be removed in a future major release */
+export type Option<A> = A | null;
+
+/** @deprecated This type will be removed in a future major release */
+export type TypographyStyles<Unit extends ScaleUnit = ScaleUnit> = {
+	fontFamily: string;
+	fontSize: Unit extends 'px' ? number : `${number}rem`;
+	lineHeight: string | number;
+	fontWeight?: (typeof fontWeights)[keyof typeof fontWeights] | FontWeight;
+	fontStyle?: 'normal' | 'italic';
+	textDecorationThickness?: number;
+};
+
+/** @deprecated This type will be removed in a future major release */
+export type TitlepieceSizes =
+	| typeof titlepieceSizes
+	| typeof remTitlepieceSizes;
+/** @deprecated This type will be removed in a future major release */
+export type HeadlineSizes = typeof headlineSizes | typeof remHeadlineSizes;
+/** @deprecated This type will be removed in a future major release */
+export type BodySizes = typeof bodySizes | typeof remBodySizes;
+/** @deprecated This type will be removed in a future major release */
+export type TextSansSizes = typeof textSansSizes | typeof remTextSansSizes;
+/** @deprecated This type will be removed in a future major release */
+export type AvailableSizes =
+	| TitlepieceSizes
+	| HeadlineSizes
+	| BodySizes
+	| TextSansSizes;
+
+/** @deprecated This type will be removed in a future major release */
+export type Categories = {
+	titlepiece: TitlepieceSizes;
+	headline: HeadlineSizes;
+	body: BodySizes;
+	textSans: TextSansSizes;
+};
+
+/** @deprecated This type will be removed in a future major release */
+export type Category = keyof Categories;
+
+/** @deprecated This type will be removed in a future major release */
+export type AvailableFontWeights = {
+	[cat in Category]?: { [weight in FontWeight]?: boolean };
+};
+
+/** @deprecated This type will be removed in a future major release */
+export type ItalicsFontWeights = {
+	[cat in Category]?: { [weight in FontWeight]?: boolean };
+};
+
+/** @deprecated This type will be removed in a future major release */
+export type TypographyConfiguration = {
+	lineHeight: LineHeight;
+	fontWeight: FontWeight;
+	fontStyle: Option<FontStyle>;
+	unit: ScaleUnit;
+};
+
+/** @deprecated This type will be removed in a future major release */
+export type FontScaleArgs = Partial<
+	Pick<TypographyConfiguration, 'fontWeight' | 'lineHeight' | 'unit'>
+> & {
+	fontStyle?: FontStyle;
+};
+
+/** @deprecated This type will be removed in a future major release */
+export type FontScaleFunction = (options?: FontScaleArgs) => TypographyStyles;
+
+// returns styles as a template literal
+/** @deprecated This type will be removed in a future major release */
+export type FontScaleFunctionStr = (options?: FontScaleArgs) => string;
+
+/** @deprecated This type will be removed in a future major release */
+export type TypographyStrFunctions<Sizes extends AvailableSizes> = {
+	[key in keyof Sizes]: FontScaleFunctionStr;
+};
+
+/** @deprecated This type will be removed in a future major release */
+export type TypographyFunctions<Sizes extends AvailableSizes> = {
+	[key in keyof Sizes]: FontScaleFunction;
+};
+
+/**
+ * This is left over from the refactor of the font style method.
+ * It is exported from source-foundations but has now been replaced
+ * by the fontStyleFunction method type definition.
+ *
+ * Before we remove it, we need to determine if it is being used.
+ *
+ * @deprecated This type will be removed in a future major release
+ */
+export type Fs = <
+	Category extends keyof Categories,
+	Level extends keyof Categories[Category],
+>(
+	category: Category,
+) => (
+	level: Level,
+	{
+		lineHeight,
+		fontWeight,
+		fontStyle,
+		unit,
+	}: {
+		lineHeight: LineHeight;
+		fontWeight: FontWeight;
+		fontStyle: Option<FontStyle>;
+		unit: ScaleUnit;
+	},
+) => TypographyStyles;
+
+/** @deprecated This type will be removed in a future major release */
 export type TypographySizes = {
 	[key in string]: number;
 };

libs/@guardian/source-foundations/src/typography/typography.test.ts → libs/@guardian/source-foundations/src/_deprecated/typography/typography.test.ts

@@ -1,4 +1,4 @@
-import { rootPixelFontSize } from '../utils/convert-value';
+import { rootPixelFontSize } from '../../utils/convert-value';
 import { pxTextSizes, remTextSizes } from './data';
 import {
 	fonts,

libs/@guardian/source-foundations/src/deprecated-exports.ts

@@ -35,4 +35,47 @@ export {
 	focus,
 } from './_deprecated/colour/palette';
 
-export type { TypographySizes } from './_deprecated/typography/types';
+export {
+	titlepiece,
+	headline,
+	body,
+	textSans,
+	titlepieceSizes,
+	headlineSizes,
+	bodySizes,
+	textSansSizes,
+	remTitlepieceSizes,
+	remHeadlineSizes,
+	remBodySizes,
+	remTextSansSizes,
+	fonts,
+	fontWeights,
+	lineHeights,
+} from './_deprecated/typography';
+
+export {
+	body as bodyObjectStyles,
+	headline as headlineObjectStyles,
+	textSans as textSansObjectStyles,
+	titlepiece as titlepieceObjectStyles,
+} from './_deprecated/typography/obj';
+
+export type {
+	ScaleUnit,
+	Category,
+	LineHeight,
+	FontWeight,
+	FontStyle,
+	FontWeightDefinition,
+	Option,
+	TypographySizes,
+	TypographyStyles,
+	TitlepieceSizes,
+	HeadlineSizes,
+	BodySizes,
+	TextSansSizes,
+	Fs,
+	FontScaleFunction,
+	FontScaleFunctionStr,
+	FontScaleArgs,
+} from './_deprecated/typography/types';