@chipmobilesdk/rn-theme 0.2.2 → 1.0.0

package/src/tokens/typography.ts

@@ -1,64 +1,144 @@
-import type {
-	TypographyConfig,
-	TypographyToken,
-	Typography,
-	RawTypography,
-} from '../types/typography';
-
-interface ScaleEntry {
-	size: number;
-	weight: TypographyToken['fontWeight'];
-	lineHeightRatio: number;
-	letterSpacing?: number;
-}
-
-const DEFAULT_BODY_SIZE = 16;
-
-const SCALE: Record<keyof RawTypography, ScaleEntry> = {
-	display: {
-		size: 57,
-		weight: '700',
-		lineHeightRatio: 1.12,
-		letterSpacing: -0.25,
-	},
-	headline: { size: 32, weight: '600', lineHeightRatio: 1.25 },
-	title: { size: 22, weight: '600', lineHeightRatio: 1.27 },
-	body: { size: 16, weight: '400', lineHeightRatio: 1.5 },
-	label: { size: 14, weight: '500', lineHeightRatio: 1.43, letterSpacing: 0.1 },
-	caption: {
-		size: 12,
-		weight: '400',
-		lineHeightRatio: 1.33,
-		letterSpacing: 0.4,
-	},
-};
-
-export function buildTypography(config?: TypographyConfig): Typography {
-	const fontFamily = config?.fontFamily ?? 'System';
-	const baseScale =
-		(config?.baseFontSize ?? DEFAULT_BODY_SIZE) / DEFAULT_BODY_SIZE;
-	const scale = baseScale * (config?.fontScale ?? 1);
-
-	function makeToken(entry: ScaleEntry): TypographyToken {
-		const fontSize = Math.round(entry.size * scale);
-		return {
-			fontSize,
-			fontWeight: entry.weight,
-			lineHeight: Math.round(fontSize * entry.lineHeightRatio),
-			fontFamily,
-			...(entry.letterSpacing != null && {
-				letterSpacing: entry.letterSpacing,
-			}),
-		};
-	}
-
-	return {
-		fontFamily,
-		display: makeToken(SCALE.display),
-		headline: makeToken(SCALE.headline),
-		title: makeToken(SCALE.title),
-		body: makeToken(SCALE.body),
-		label: makeToken(SCALE.label),
-		caption: makeToken(SCALE.caption),
-	};
-}
+import type {
+	FontConfig,
+	FontToken,
+	FontWeightName,
+	FontWeights,
+	FontWeightValue,
+	Typography,
+	TypographyConfig,
+	TypographyRole,
+	TypographyStyleName,
+	TypographyToken,
+} from '../types/typography';
+
+export type Platform = 'ios' | 'android';
+
+const DEFAULT_FONT_FAMILY = 'System';
+const DEFAULT_BODY_SIZE = 16;
+
+export const FONT_WEIGHTS: FontWeights = {
+	regular: '400',
+	medium: '500',
+	semibold: '600',
+	bold: '700',
+	heavy: '800',
+};
+
+const WEIGHT_ORDER: FontWeightName[] = ['regular', 'medium', 'semibold', 'bold', 'heavy'];
+
+/** Android: the per-weight family already carries the weight. */
+const ANDROID_MAPPED_WEIGHT: FontWeightValue = 'normal';
+
+interface RoleScale {
+	/** Small, medium, large. Medium keeps the 0.2.x size (plan D-6). */
+	sizes: [number, number, number];
+	weight: FontWeightName;
+	lineHeightRatio: number;
+	letterSpacing?: number;
+}
+
+const SCALE: Record<TypographyRole, RoleScale> = {
+	display: { sizes: [45, 57, 64], weight: 'bold', lineHeightRatio: 1.12, letterSpacing: -0.25 },
+	headline: { sizes: [28, 32, 36], weight: 'semibold', lineHeightRatio: 1.25 },
+	title: { sizes: [18, 22, 24], weight: 'semibold', lineHeightRatio: 1.27 },
+	body: { sizes: [14, 16, 18], weight: 'regular', lineHeightRatio: 1.5 },
+	label: { sizes: [12, 14, 16], weight: 'medium', lineHeightRatio: 1.43, letterSpacing: 0.1 },
+	caption: { sizes: [11, 12, 13], weight: 'regular', lineHeightRatio: 1.33, letterSpacing: 0.4 },
+};
+
+const SIZE_SUFFIXES = ['Small', '', 'Large'] as const;
+
+/** The configured weight closest to the requested one; ties go to the heavier. */
+function nearestWeight(
+	requested: FontWeightName,
+	available: Partial<Record<FontWeightName, string>>,
+): FontWeightName | undefined {
+	const target = WEIGHT_ORDER.indexOf(requested);
+
+	return WEIGHT_ORDER.filter(weight => available[weight] != null).sort(
+		(a, b) =>
+			Math.abs(WEIGHT_ORDER.indexOf(a) - target) - Math.abs(WEIGHT_ORDER.indexOf(b) - target) ||
+			WEIGHT_ORDER.indexOf(b) - WEIGHT_ORDER.indexOf(a),
+	)[0];
+}
+
+function warnMissingWeight(platform: Platform, weight: FontWeightName, used: FontWeightName) {
+	if (__DEV__) {
+		console.warn(
+			`[rn-theme] typography.fonts.${platform} has no "${weight}" font; using "${used}" instead.`,
+		);
+	}
+}
+
+/**
+ * Resolves the family and weight a style needs for one named weight on one
+ * platform (spec US-2).
+ */
+export function buildFonts(config: TypographyConfig | undefined, platform: Platform) {
+	const fonts: FontConfig = config?.fonts ?? {};
+	const family = fonts.family ?? config?.fontFamily ?? DEFAULT_FONT_FAMILY;
+	const perWeight = fonts[platform];
+	const warned = new Set<FontWeightName>();
+
+	const resolve = (weight: FontWeightName): FontToken => {
+		// iOS picks weights inside one family, so a partial iOS map only renames
+		// the weights it lists; Android needs a file per weight, hence nearest.
+		const nearest =
+			platform === 'ios' ? (perWeight?.[weight] && weight) : perWeight && nearestWeight(weight, perWeight);
+
+		if (!perWeight || !nearest) {
+			return { fontFamily: family, fontWeight: FONT_WEIGHTS[weight] };
+		}
+
+		if (nearest !== weight && !warned.has(weight)) {
+			warned.add(weight);
+			warnMissingWeight(platform, weight, nearest);
+		}
+
+		const fontFamily = perWeight[nearest] as string;
+
+		return {
+			fontFamily,
+			fontWeight: platform === 'android' ? ANDROID_MAPPED_WEIGHT : FONT_WEIGHTS[weight],
+		};
+	};
+
+	const font = {} as Record<FontWeightName, FontToken>;
+
+	for (const weight of WEIGHT_ORDER) {
+		font[weight] = resolve(weight);
+	}
+
+	return { family, font };
+}
+
+export function buildTypography(
+	config: TypographyConfig | undefined,
+	font: Record<FontWeightName, FontToken>,
+	family: string,
+): Typography {
+	const scale = ((config?.baseFontSize ?? DEFAULT_BODY_SIZE) / DEFAULT_BODY_SIZE) * (config?.fontScale ?? 1);
+	const typography = { fontFamily: family } as Typography;
+
+	for (const role of Object.keys(SCALE) as TypographyRole[]) {
+		const entry = SCALE[role];
+
+		entry.sizes.forEach((size, index) => {
+			const fontSize = Math.round(size * scale);
+			const token: TypographyToken = {
+				fontSize,
+				lineHeight: Math.round(fontSize * entry.lineHeightRatio),
+				...font[entry.weight],
+				...(entry.letterSpacing != null && { letterSpacing: entry.letterSpacing }),
+			};
+
+			typography[`${role}${SIZE_SUFFIXES[index]}` as TypographyStyleName] = token;
+		});
+	}
+
+	return typography;
+}
+
+export function buildFontWeight(): FontWeights {
+	return { ...FONT_WEIGHTS };
+}

package/src/types/brand.ts

@@ -1,5 +1,21 @@
+/**
+ * Opaque brand colours. Each keeps its hue and chroma; roles take fixed tones.
+ *
+ * Accepted colour strings everywhere in the package: `#RGB`, `#RGBA`,
+ * `#RRGGBB`, `#RRGGBBAA`, `rgb(r, g, b)`, `rgba(r, g, b, a)`.
+ */
 export interface BrandColors {
 	primary: string;
 	secondary: string;
 	tertiary: string;
 }
+
+/** Optional opaque seeds replacing the default neutral and semantic hues. */
+export interface SeedColors {
+	/** Without it, neutrals take the primary hue at a very low chroma. */
+	neutral?: string;
+	error?: string;
+	success?: string;
+	warning?: string;
+	info?: string;
+}

package/src/types/colors.ts

@@ -1,23 +1,92 @@
-export interface ThemeColors {
+export type ColorScheme = 'light' | 'dark';
+
+/** Colours whose roles come in sets of four: X, onX, XContainer, onXContainer. */
+export type AccentRoleName =
+	| 'primary'
+	| 'secondary'
+	| 'tertiary'
+	| 'error'
+	| 'success'
+	| 'warning'
+	| 'info';
+
+export interface ColorRoles {
 	primary: string;
-	primaryContainer: string;
 	onPrimary: string;
+	primaryContainer: string;
+	onPrimaryContainer: string;
 	secondary: string;
-	secondaryContainer: string;
 	onSecondary: string;
+	secondaryContainer: string;
+	onSecondaryContainer: string;
 	tertiary: string;
-	tertiaryContainer: string;
 	onTertiary: string;
-	background: string;
-	surface: string;
-	surfaceVariant: string;
-	onBackground: string;
-	onSurface: string;
-	border: string;
+	tertiaryContainer: string;
+	onTertiaryContainer: string;
+	/** Error text/fill; ≥ 4.5:1 on `background` and `surface`. */
 	error: string;
+	onError: string;
+	errorContainer: string;
+	onErrorContainer: string;
 	success: string;
+	onSuccess: string;
+	successContainer: string;
+	onSuccessContainer: string;
 	warning: string;
+	onWarning: string;
+	warningContainer: string;
+	onWarningContainer: string;
 	info: string;
-	disabled: string;
+	onInfo: string;
+	infoContainer: string;
+	onInfoContainer: string;
+	background: string;
+	onBackground: string;
+	surface: string;
+	onSurface: string;
+	surfaceVariant: string;
+	/** Muted text; ≥ 4.5:1 on `background`, `surface` and `surfaceVariant`. */
+	onSurfaceVariant: string;
+	surfaceContainerLowest: string;
+	surfaceContainerLow: string;
+	surfaceContainer: string;
+	surfaceContainerHigh: string;
+	surfaceContainerHighest: string;
+	inverseSurface: string;
+	inverseOnSurface: string;
+	inversePrimary: string;
+	/** Boundary of interactive components; ≥ 3:1 on `background` and `surface`. */
+	outline: string;
+	/** Decorative dividers; no contrast guarantee. */
+	outlineVariant: string;
+	scrim: string;
 	shadow: string;
+	/**
+	 * Inactive content. A state colour, exempt from contrast targets
+	 * (WCAG 1.4.3) — never use it for readable muted text; that is
+	 * `onSurfaceVariant`.
+	 */
+	disabled: string;
+}
+
+export type StandardToneName =
+	| 'neutral'
+	| 'primary'
+	| 'info'
+	| 'success'
+	| 'warning'
+	| 'error';
+
+/** A matched colour set for one tone, for use with `byTone`. */
+export interface ToneColors {
+	/** Text or icon in this tone on `background`/`surface` (≥ 4.5:1). */
+	fg: string;
+	container: string;
+	/** Text on `container` (≥ 4.5:1). */
+	onContainer: string;
+	/** Boundary in this tone (≥ 3:1 on `background`). */
+	border: string;
+	fill: string;
+	/** Text on `fill` (≥ 4.5:1). */
+	onFill: string;
 }

package/src/types/index.ts

@@ -1,11 +1,50 @@
-export type { BrandColors } from './brand';
-export type { ThemeColors } from './colors';
-export type { TypographyConfig, TypographyToken, Typography } from './typography';
+export type { BrandColors, SeedColors } from './brand';
 export type {
-	SpacingTokens,
+	AccentRoleName,
+	ColorRoles,
+	ColorScheme,
+	StandardToneName,
+	ToneColors,
+} from './colors';
+export type {
+	FontConfig,
+	FontToken,
+	FontWeightName,
+	FontWeights,
+	FontWeightValue,
+	Typography,
+	TypographyConfig,
+	TypographyRole,
+	TypographyStyleName,
+	TypographyToken,
+} from './typography';
+export type {
+	BorderWidthTokens,
+	EasingCurve,
+	MotionTokens,
+	OpacityTokens,
 	RadiusTokens,
 	ShadowToken,
 	ShadowTokens,
+	SizeTokens,
+	SpacingKey,
+	SpacingTokens,
 	ZIndexTokens,
 } from './tokens';
-export type { DeepPartial, StyleConfig, StyleTheme } from './style';
+export type {
+	BaseTheme,
+	BorderPresets,
+	BoxPresets,
+	DeepPartial,
+	EmptyExtension,
+	ExtendContext,
+	InlinePreset,
+	NamedThemeConfig,
+	StackPreset,
+	TextPreset,
+	TextPresets,
+	Theme,
+	ThemeConfig,
+	ThemeName,
+	Themes,
+} from './theme';

package/src/types/theme.ts

@@ -0,0 +1,161 @@
+import type { BrandColors, SeedColors } from './brand';
+import type { ColorRoles, ColorScheme, StandardToneName, ToneColors } from './colors';
+import type {
+	BorderWidthTokens,
+	MotionTokens,
+	OpacityTokens,
+	RadiusTokens,
+	ShadowTokens,
+	SizeTokens,
+	SpacingKey,
+	SpacingTokens,
+	ZIndexTokens,
+} from './tokens';
+import type {
+	FontToken,
+	FontWeightName,
+	FontWeights,
+	Typography,
+	TypographyConfig,
+	TypographyToken,
+} from './typography';
+
+export type DeepPartial<T> = {
+	[K in keyof T]?: T[K] extends readonly unknown[]
+		? T[K]
+		: T[K] extends object
+			? DeepPartial<T[K]>
+			: T[K];
+};
+
+/** A typography token with its colour, ready to spread into a text style. */
+export interface TextPreset extends TypographyToken {
+	color: string;
+}
+
+export interface TextPresets {
+	body: TextPreset;
+	bodyMuted: TextPreset;
+	label: TextPreset;
+	labelMuted: TextPreset;
+	caption: TextPreset;
+	title: TextPreset;
+	headline: TextPreset;
+	/** Uses the contrast-exempt `disabled` colour. */
+	disabled: TextPreset;
+}
+
+export interface StackPreset {
+	flexDirection: 'column';
+	gap: number;
+}
+
+export interface InlinePreset {
+	flexDirection: 'row';
+	alignItems: 'center';
+	gap: number;
+}
+
+export interface BorderPresets {
+	/** Hairline divider on every side (`outlineVariant`). */
+	hairline: { borderWidth: number; borderColor: string };
+	/** Divider above (`outlineVariant`). */
+	top: { borderTopWidth: number; borderTopColor: string };
+	/** Divider below (`outlineVariant`). */
+	bottom: { borderBottomWidth: number; borderBottomColor: string };
+	/** Boundary of an interactive component (`outline`, ≥ 3:1). */
+	all: { borderWidth: number; borderColor: string };
+}
+
+export interface BoxPresets {
+	outlined: {
+		borderWidth: number;
+		borderColor: string;
+		borderRadius: number;
+		padding: number;
+		gap: number;
+	};
+	card: { backgroundColor: string; borderRadius: number; padding: number; gap: number };
+	sheet: {
+		backgroundColor: string;
+		borderTopLeftRadius: number;
+		borderTopRightRadius: number;
+		padding: number;
+		gap: number;
+	};
+	touchTarget: { minWidth: number; minHeight: number; justifyContent: 'center' };
+}
+
+export interface BaseTheme<TTone extends string = never> {
+	color: ColorRoles;
+	tone: Record<StandardToneName | TTone, ToneColors>;
+	typography: Typography;
+	/** Family + weight per named weight, resolved for the current platform. */
+	font: Record<FontWeightName, FontToken>;
+	fontWeight: FontWeights;
+	spacing: SpacingTokens;
+	radius: RadiusTokens;
+	borderWidth: BorderWidthTokens;
+	size: SizeTokens;
+	opacity: OpacityTokens;
+	motion: MotionTokens;
+	shadow: ShadowTokens;
+	zIndex: ZIndexTokens;
+	/** Ceiling for `maxFontSizeMultiplier` on the app's `Text`. */
+	maxFontScale: number;
+	/** Chart series colours (≥ 3:1 on `surface`), starting at the primary hue. */
+	categorical: string[];
+	text: TextPresets;
+	stack: Record<SpacingKey, StackPreset>;
+	inline: Record<SpacingKey, InlinePreset>;
+	border: BorderPresets;
+	box: BoxPresets;
+}
+
+export type EmptyExtension = Record<never, never>;
+
+export type Theme<TExt extends object = EmptyExtension, TTone extends string = never> = BaseTheme<TTone> &
+	TExt;
+
+export type ThemeName<TName extends string = never> = 'light' | 'dark' | TName;
+
+export type Themes<
+	TExt extends object = EmptyExtension,
+	TTone extends string = never,
+	TName extends string = never,
+> = Record<ThemeName<TName>, Theme<TExt, TTone>>;
+
+export interface ExtendContext<TTone extends string = never, TName extends string = never> {
+	name: ThemeName<TName>;
+	scheme: ColorScheme;
+	theme: BaseTheme<TTone>;
+}
+
+/** An extra theme beyond light and dark. Omitted colours come from the base config. */
+export interface NamedThemeConfig<TTone extends string = never> {
+	scheme: ColorScheme;
+	brandColors?: BrandColors;
+	seeds?: SeedColors;
+	tones?: Partial<Record<TTone, string>>;
+}
+
+/** Extension keys may not replace base groups. */
+type NoBaseKeys = { [K in keyof BaseTheme]?: never };
+
+export interface ThemeConfig<
+	TExt extends object = EmptyExtension,
+	TTone extends string = never,
+	TName extends string = never,
+> {
+	brandColors: BrandColors;
+	seeds?: SeedColors;
+	/** Custom tones from one opaque seed each, e.g. `{ accent: '#BD260F' }`. */
+	tones?: Record<TTone, string>;
+	typography?: TypographyConfig;
+	/** App-specific token groups, derived per theme from the generated tokens. */
+	extend?: (context: ExtendContext<TTone, TName>) => TExt & NoBaseKeys;
+	themes?: Record<TName, NamedThemeConfig<TTone>>;
+	overrides?: NoInfer<Partial<Record<ThemeName<TName>, DeepPartial<Theme<TExt, TTone>>>>>;
+	/** Throw instead of warning when an override breaks a contrast guarantee. */
+	strict?: boolean;
+}

package/src/types/tokens.ts

@@ -1,13 +1,23 @@
 export interface SpacingTokens {
+	none: number;
+	xxs: number;
 	xs: number;
 	sm: number;
+	smPlus: number;
 	md: number;
+	mdPlus: number;
 	lg: number;
 	xl: number;
+	xlPlus: number;
 	xxl: number;
+	xxxl: number;
 }
 
+export type SpacingKey = keyof SpacingTokens;
+
 export interface RadiusTokens {
+	none: number;
+	xs: number;
 	sm: number;
 	md: number;
 	lg: number;
@@ -15,12 +25,44 @@ export interface RadiusTokens {
 	full: number;
 }
 
+export interface BorderWidthTokens {
+	hairline: number;
+	thin: number;
+	thick: number;
+}
+
+export interface SizeTokens {
+	/** Minimum touch target side, in points (WCAG 2.5.8 / standards V). */
+	touchTarget: number;
+	icon: { sm: number; md: number; lg: number };
+}
+
+/** Material 3 state-layer and disabled opacities. */
+export interface OpacityTokens {
+	hover: number;
+	focus: number;
+	pressed: number;
+	dragged: number;
+	disabledContent: number;
+	disabledContainer: number;
+}
+
+/** Cubic-bezier control points `[x1, y1, x2, y2]`, e.g. for `Easing.bezier`. */
+export type EasingCurve = [number, number, number, number];
+
+export interface MotionTokens {
+	duration: { short: number; medium: number; long: number };
+	easing: {
+		standard: EasingCurve;
+		emphasized: EasingCurve;
+		decelerate: EasingCurve;
+		accelerate: EasingCurve;
+	};
+}
+
 export interface ShadowToken {
-	shadowColor: string;
-	shadowOffset: { width: number; height: number };
-	shadowOpacity: number;
-	shadowRadius: number;
-	elevation: number;
+	/** CSS-style shadow list, rendered by React Native on iOS and Android. */
+	boxShadow: string;
 }
 
 export interface ShadowTokens {

package/src/types/typography.ts

@@ -1,26 +1,62 @@
+export type FontWeightName = 'regular' | 'medium' | 'semibold' | 'bold' | 'heavy';
+
+/** The weight strings the package emits; each is a valid React Native `fontWeight`. */
+export type FontWeightValue = 'normal' | '400' | '500' | '600' | '700' | '800' | '900';
+
+/**
+ * Custom font files per weight. Android cannot pick a weight inside a family,
+ * so every weight needs its own family name there; iOS resolves weights within
+ * one family unless a per-weight name is given.
+ */
+export interface FontConfig {
+	/** Family used where no per-weight name applies. */
+	family?: string;
+	ios?: Partial<Record<FontWeightName, string>>;
+	android?: Partial<Record<FontWeightName, string>>;
+}
+
 export interface TypographyConfig {
+	/** Single family for every weight (0.2.x behaviour). Defaults to `System`. */
 	fontFamily?: string;
+	fonts?: FontConfig;
 	baseFontSize?: number;
+	/** Design-time multiplier. It does not track the OS text-size setting. */
 	fontScale?: number;
+	/**
+	 * Ceiling for the OS text-size multiplier, applied by the app's `Text`
+	 * through `maxFontSizeMultiplier`. Defaults to 2 (WCAG 1.4.4).
+	 */
+	maxFontScale?: number;
 }
 
+export type TypographyRole = 'display' | 'headline' | 'title' | 'body' | 'label' | 'caption';
+
+export type TypographyStyleName =
+	| TypographyRole
+	| `${TypographyRole}Small`
+	| `${TypographyRole}Large`;
+
 export interface TypographyToken {
 	fontSize: number;
-	fontWeight: '400' | '500' | '600' | '700' | '800' | '900';
 	lineHeight: number;
-	fontFamily?: string;
+	fontWeight: FontWeightValue;
+	fontFamily: string;
 	letterSpacing?: number;
 }
 
-export interface RawTypography {
-	display: TypographyToken;
-	headline: TypographyToken;
-	title: TypographyToken;
-	body: TypographyToken;
-	label: TypographyToken;
-	caption: TypographyToken;
+/** The six 0.2.x role names resolve to the medium size. */
+export type Typography = { fontFamily: string } & Record<TypographyStyleName, TypographyToken>;
+
+/** The fixed weight scale behind the weight names. */
+export interface FontWeights {
+	regular: '400';
+	medium: '500';
+	semibold: '600';
+	bold: '700';
+	heavy: '800';
 }
 
-export interface Typography extends RawTypography {
+export interface FontToken {
 	fontFamily: string;
+	fontWeight: FontWeightValue;
 }