@chipmobilesdk/rn-theme 0.2.2 → 1.0.1

package/src/theme/buildThemes.ts

@@ -0,0 +1,186 @@
+import { Platform as ReactNativePlatform } from 'react-native';
+import { buildCategorical } from '../color/categorical';
+import { auditTheme } from '../color/contrast';
+import { buildColorRoles, buildPalettes, buildTones } from '../color/roles';
+import { buildPresets, PRESET_KEYS } from '../presets/themePresets';
+import {
+	buildBorderWidth,
+	buildMotion,
+	buildOpacity,
+	buildRadius,
+	buildShadows,
+	buildSize,
+	buildSpacing,
+	buildZIndex,
+	DEFAULT_MAX_FONT_SCALE,
+} from '../tokens/defaults';
+import { buildFonts, buildFontWeight, buildTypography, type Platform } from '../tokens/typography';
+import type { ColorScheme } from '../types/colors';
+import type {
+	BaseTheme,
+	EmptyExtension,
+	Theme,
+	ThemeConfig,
+	ThemeName,
+	Themes,
+} from '../types/theme';
+import type { FontToken, FontWeightName } from '../types/typography';
+import { describeFailures, ThemeContrastError } from './errors';
+import { mergeOverrides, pick } from './overrides';
+import { validateThemeConfig } from './validateThemeConfig';
+
+export interface BuildThemesOptions {
+	/** Platform whose font resolution applies. Defaults to the running platform. */
+	platform?: Platform;
+}
+
+/** Groups that come straight from tokens (presets and tones are derived after). */
+const TOKEN_KEYS = [
+	'color',
+	'typography',
+	'font',
+	'fontWeight',
+	'spacing',
+	'radius',
+	'borderWidth',
+	'size',
+	'opacity',
+	'motion',
+	'shadow',
+	'zIndex',
+	'maxFontScale',
+	'categorical',
+] as const;
+
+interface ThemeSource {
+	name: string;
+	scheme: ColorScheme;
+	config: ThemeConfig<object, string, string>;
+	/** Shared by light and dark: palettes cache their tones (spec FR-4). */
+	palettes: ReturnType<typeof buildPalettes>;
+}
+
+function cloneFonts(font: Record<FontWeightName, FontToken>): Record<FontWeightName, FontToken> {
+	const copy = {} as Record<FontWeightName, FontToken>;
+
+	for (const [weight, token] of Object.entries(font) as Array<[FontWeightName, FontToken]>) {
+		copy[weight] = { ...token };
+	}
+
+	return copy;
+}
+
+function buildOne(
+	source: ThemeSource,
+	fonts: ReturnType<typeof buildFonts>,
+	overrides: unknown,
+): object {
+	const { name, scheme, config, palettes } = source;
+	const path = `overrides.${name}`;
+	const color = buildColorRoles(palettes, scheme);
+
+	const generated = {
+		color,
+		typography: buildTypography(config.typography, fonts.font, fonts.family),
+		font: cloneFonts(fonts.font),
+		fontWeight: buildFontWeight(),
+		spacing: buildSpacing(),
+		radius: buildRadius(),
+		borderWidth: buildBorderWidth(),
+		size: buildSize(),
+		opacity: buildOpacity(),
+		motion: buildMotion(),
+		shadow: buildShadows(color.shadow),
+		zIndex: buildZIndex(),
+		maxFontScale: config.typography?.maxFontScale ?? DEFAULT_MAX_FONT_SCALE,
+		categorical: buildCategorical(config.brandColors.primary, scheme),
+	};
+	const tokens = mergeOverrides(generated, pick(overrides, TOKEN_KEYS), path);
+	const tone = mergeOverrides(
+		buildTones<string>(palettes, color, scheme),
+		pick(overrides, ['tone'])?.tone,
+		`${path}.tone`,
+	);
+	const presets = mergeOverrides(buildPresets(tokens), pick(overrides, PRESET_KEYS), path);
+	const base = { ...tokens, tone, ...presets } as BaseTheme<string>;
+
+	if (!config.extend) {
+		return base;
+	}
+
+	const extension = config.extend({ name, scheme, theme: base });
+	const extensionOverrides = pick(overrides, Object.keys(extension));
+
+	return { ...base, ...mergeOverrides(extension, extensionOverrides, path) };
+}
+
+function checkContrast(name: string, theme: object, strict: boolean): void {
+	if (!__DEV__ && !strict) {
+		return;
+	}
+
+	const failures = auditTheme(theme);
+
+	if (failures.length === 0) {
+		return;
+	}
+
+	if (strict) {
+		throw new ThemeContrastError(name, failures);
+	}
+
+	console.warn(
+		`[rn-theme] Theme "${name}" breaks contrast guarantees after overrides:\n${describeFailures(failures)}`,
+	);
+}
+
+/**
+ * Builds every theme from brand config — pure, with no Unistyles dependency
+ * (spec AC-9.4). `createUnistylesConfig` wraps this; call it directly to feed
+ * tokens to other libraries or tests.
+ */
+export function buildThemes<
+	TExt extends object = EmptyExtension,
+	TTone extends string = never,
+	TName extends string = never,
+>(
+	config: ThemeConfig<TExt, TTone, TName>,
+	options?: BuildThemesOptions,
+): Themes<TExt, TTone, TName> {
+	validateThemeConfig(config);
+
+	const loose = config as unknown as ThemeConfig<object, string, string>;
+	const platform = options?.platform ?? (ReactNativePlatform.OS === 'ios' ? 'ios' : 'android');
+	const fonts = buildFonts(loose.typography, platform);
+	const basePalettes = buildPalettes(loose);
+	const sources: ThemeSource[] = [
+		{ name: 'light', scheme: 'light', config: loose, palettes: basePalettes },
+		{ name: 'dark', scheme: 'dark', config: loose, palettes: basePalettes },
+		...Object.entries(loose.themes ?? {}).map(([name, named]) => {
+			const namedConfig = {
+				...loose,
+				brandColors: named.brandColors ?? loose.brandColors,
+				seeds: { ...loose.seeds, ...named.seeds },
+				tones: { ...loose.tones, ...named.tones } as Record<string, string>,
+			};
+
+			return {
+				name,
+				scheme: named.scheme,
+				config: namedConfig,
+				palettes: buildPalettes(namedConfig),
+			};
+		}),
+	];
+	const themes: Record<string, object> = {};
+
+	for (const source of sources) {
+		const overrides = (loose.overrides as Record<string, unknown> | undefined)?.[source.name];
+		const theme = buildOne(source, fonts, overrides);
+
+		checkContrast(source.name, theme, loose.strict === true);
+		themes[source.name] = theme;
+	}
+
+	return themes as Record<ThemeName<TName>, Theme<TExt, TTone>>;
+}

package/src/theme/errors.ts

@@ -0,0 +1,34 @@
+import type { ContrastFailure } from '../color/contrast';
+
+/** Invalid configuration or override; `path` names the offending field. */
+export class ThemeConfigError extends Error {
+	readonly path: string;
+
+	constructor(path: string, message: string) {
+		super(`${path}: ${message}`);
+		this.name = 'ThemeConfigError';
+		this.path = path;
+	}
+}
+
+/** Thrown in `strict` mode when a theme breaks a contrast guarantee. */
+export class ThemeContrastError extends Error {
+	readonly themeName: string;
+	readonly failures: ContrastFailure[];
+
+	constructor(themeName: string, failures: ContrastFailure[]) {
+		super(`Theme "${themeName}" breaks contrast guarantees:\n${describeFailures(failures)}`);
+		this.name = 'ThemeContrastError';
+		this.themeName = themeName;
+		this.failures = failures;
+	}
+}
+
+export function describeFailures(failures: ContrastFailure[]): string {
+	return failures
+		.map(
+			({ foreground, background, ratio, target }) =>
+				`  ${foreground} on ${background}: ${ratio}:1 (needs ${target}:1)`,
+		)
+		.join('\n');
+}

package/src/theme/overrides.ts

@@ -0,0 +1,147 @@
+import { isValidColor } from '../color/parse';
+import { ThemeConfigError } from './errors';
+
+type PlainObject = Record<string, unknown>;
+
+export function isPlainObject(value: unknown): value is PlainObject {
+	return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/** Optional style keys an override may add although the generated token omits them. */
+const OPTIONAL_NUMBER_KEYS = new Set(['letterSpacing']);
+
+/** Groups whose every leaf is a colour. */
+const COLOR_GROUPS = new Set(['color', 'tone', 'categorical']);
+
+function isColorPath(segments: string[]): boolean {
+	const leaf = segments.at(-1) ?? '';
+
+	return COLOR_GROUPS.has(segments[0]) || leaf === 'color' || leaf.endsWith('Color');
+}
+
+function assertFiniteNumber(value: unknown, path: string): void {
+	if (typeof value !== 'number' || !Number.isFinite(value)) {
+		throw new ThemeConfigError(path, 'must be a finite number.');
+	}
+}
+
+function validateLeaf(value: unknown, base: unknown, segments: string[], path: string): void {
+	if (typeof base === 'number') {
+		assertFiniteNumber(value, path);
+		return;
+	}
+
+	if (typeof base !== 'string') {
+		return;
+	}
+
+	if (typeof value !== 'string') {
+		throw new ThemeConfigError(path, 'must be a string.');
+	}
+
+	// A string that is a colour today (e.g. an `extend` token) must stay one.
+	if ((isColorPath(segments) || isValidColor(base)) && !isValidColor(value)) {
+		throw new ThemeConfigError(path, `"${value}" is not a supported colour.`);
+	}
+}
+
+interface Entry {
+	key: string;
+	value: unknown;
+	baseValue: unknown;
+	path: string;
+	segments: string[];
+}
+
+function mergeArray({ value, baseValue, path, segments }: Entry): unknown[] {
+	if (!Array.isArray(value)) {
+		throw new ThemeConfigError(path, 'must be an array.');
+	}
+
+	const sample: unknown = Array.isArray(baseValue) ? baseValue[0] : undefined;
+	value.forEach((item, index) => validateLeaf(item, sample, segments, `${path}.${index}`));
+
+	return [...value];
+}
+
+function mergeEntry(entry: Entry): unknown {
+	const { value, baseValue, path, segments } = entry;
+
+	if (Array.isArray(baseValue)) {
+		return mergeArray(entry);
+	}
+
+	if (isPlainObject(baseValue)) {
+		return mergeOverrides(baseValue, value, path, segments);
+	}
+
+	validateLeaf(value, baseValue, segments, path);
+
+	return value;
+}
+
+/**
+ * Merges `overrides` into a fresh copy of `base`, validating as it goes:
+ * keys must exist in `base`, colours must parse, numbers must be finite.
+ * Arrays are replaced whole. `base` itself is never mutated.
+ */
+export function mergeOverrides<T>(
+	base: T,
+	overrides: unknown,
+	path: string,
+	segments: string[] = [],
+): T {
+	if (overrides == null) {
+		return base;
+	}
+
+	if (!isPlainObject(overrides) || !isPlainObject(base)) {
+		throw new ThemeConfigError(path, 'must be an object.');
+	}
+
+	const result: PlainObject = { ...base };
+
+	for (const [key, value] of Object.entries(overrides)) {
+		const entry: Entry = {
+			key,
+			value,
+			baseValue: base[key],
+			path: `${path}.${key}`,
+			segments: [...segments, key],
+		};
+
+		if (value === undefined) {
+			continue;
+		}
+
+		if (key in base) {
+			result[key] = mergeEntry(entry);
+		} else if (OPTIONAL_NUMBER_KEYS.has(key)) {
+			assertFiniteNumber(value, entry.path);
+			result[key] = value;
+		} else {
+			throw new ThemeConfigError(
+				entry.path,
+				'does not exist on the theme. Add new tokens through `extend`.',
+			);
+		}
+	}
+
+	return result as T;
+}
+
+export function pick(source: unknown, keys: readonly string[]): PlainObject | undefined {
+	if (!isPlainObject(source)) {
+		return undefined;
+	}
+
+	const picked: PlainObject = {};
+
+	for (const key of keys) {
+		if (key in source) {
+			picked[key] = source[key];
+		}
+	}
+
+	return picked;
+}

package/src/theme/validateThemeConfig.ts

@@ -0,0 +1,177 @@
+import { isOpaqueColor } from '../color/parse';
+import type { FontWeightName } from '../types/typography';
+import { ThemeConfigError } from './errors';
+import { isPlainObject } from './overrides';
+
+const BRAND_KEYS = ['primary', 'secondary', 'tertiary'] as const;
+const SEED_KEYS = ['neutral', 'error', 'success', 'warning', 'info'] as const;
+const FONT_WEIGHT_NAMES: FontWeightName[] = ['regular', 'medium', 'semibold', 'bold', 'heavy'];
+const SCHEMES = new Set(['light', 'dark']);
+const RESERVED_THEME_NAMES = new Set(['light', 'dark']);
+
+function assertObject(value: unknown, path: string): asserts value is Record<string, unknown> {
+	if (!isPlainObject(value)) {
+		throw new ThemeConfigError(path, 'must be an object.');
+	}
+}
+
+function assertOpaqueColor(value: unknown, path: string): void {
+	if (!isOpaqueColor(value)) {
+		throw new ThemeConfigError(
+			path,
+			`must be an opaque colour (#RGB, #RRGGBB or rgb()), received ${JSON.stringify(value)}.`,
+		);
+	}
+}
+
+function assertNonEmptyString(value: unknown, path: string): void {
+	if (typeof value !== 'string' || value.trim().length === 0) {
+		throw new ThemeConfigError(path, 'must be a non-empty string.');
+	}
+}
+
+function assertPositiveNumber(value: unknown, path: string): void {
+	if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0) {
+		throw new ThemeConfigError(path, 'must be a positive finite number.');
+	}
+}
+
+function validateColorRecord(value: unknown, path: string, keys?: readonly string[]): void {
+	if (value == null) {
+		return;
+	}
+
+	assertObject(value, path);
+
+	for (const [key, color] of Object.entries(value)) {
+		if (keys && !keys.includes(key)) {
+			throw new ThemeConfigError(`${path}.${key}`, `is not one of ${keys.join(', ')}.`);
+		}
+		if (color !== undefined) {
+			assertOpaqueColor(color, `${path}.${key}`);
+		}
+	}
+}
+
+function validateBrandColors(value: unknown, path: string): void {
+	assertObject(value, path);
+
+	for (const key of BRAND_KEYS) {
+		assertOpaqueColor(value[key], `${path}.${key}`);
+	}
+}
+
+function validateFontMap(value: unknown, path: string): void {
+	if (value == null) {
+		return;
+	}
+
+	assertObject(value, path);
+
+	for (const [weight, family] of Object.entries(value)) {
+		if (!FONT_WEIGHT_NAMES.includes(weight as FontWeightName)) {
+			throw new ThemeConfigError(
+				`${path}.${weight}`,
+				`is not one of ${FONT_WEIGHT_NAMES.join(', ')}.`,
+			);
+		}
+		assertNonEmptyString(family, `${path}.${weight}`);
+	}
+}
+
+function validateTypography(value: unknown): void {
+	if (value == null) {
+		return;
+	}
+
+	assertObject(value, 'typography');
+
+	if (value.fontFamily != null) {
+		assertNonEmptyString(value.fontFamily, 'typography.fontFamily');
+	}
+
+	for (const key of ['baseFontSize', 'fontScale', 'maxFontScale'] as const) {
+		if (value[key] != null) {
+			assertPositiveNumber(value[key], `typography.${key}`);
+		}
+	}
+
+	if (value.fonts != null) {
+		assertObject(value.fonts, 'typography.fonts');
+		if (value.fonts.family != null) {
+			assertNonEmptyString(value.fonts.family, 'typography.fonts.family');
+		}
+		validateFontMap(value.fonts.ios, 'typography.fonts.ios');
+		validateFontMap(value.fonts.android, 'typography.fonts.android');
+	}
+}
+
+function validateNamedThemes(value: unknown): void {
+	if (value == null) {
+		return;
+	}
+
+	assertObject(value, 'themes');
+
+	for (const [name, theme] of Object.entries(value)) {
+		const path = `themes.${name}`;
+
+		if (RESERVED_THEME_NAMES.has(name)) {
+			throw new ThemeConfigError(
+				path,
+				'light and dark are built in; customise them with overrides.',
+			);
+		}
+
+		assertObject(theme, path);
+
+		if (!SCHEMES.has(theme.scheme as string)) {
+			throw new ThemeConfigError(`${path}.scheme`, "must be 'light' or 'dark'.");
+		}
+
+		if (theme.brandColors != null) {
+			validateBrandColors(theme.brandColors, `${path}.brandColors`);
+		}
+
+		validateColorRecord(theme.seeds, `${path}.seeds`, SEED_KEYS);
+		validateColorRecord(theme.tones, `${path}.tones`);
+	}
+}
+
+function validateOverrideThemes(value: unknown, themeNames: string[]): void {
+	if (value == null) {
+		return;
+	}
+
+	assertObject(value, 'overrides');
+
+	for (const name of Object.keys(value)) {
+		if (!themeNames.includes(name)) {
+			throw new ThemeConfigError(`overrides.${name}`, `is not a theme (${themeNames.join(', ')}).`);
+		}
+	}
+}
+
+/** Validates the config shape; override values are validated while merging. */
+export function validateThemeConfig(config: unknown): void {
+	assertObject(config, 'config');
+	validateBrandColors(config.brandColors, 'brandColors');
+	validateColorRecord(config.seeds, 'seeds', SEED_KEYS);
+	validateColorRecord(config.tones, 'tones');
+	validateTypography(config.typography);
+	validateNamedThemes(config.themes);
+
+	if (config.extend != null && typeof config.extend !== 'function') {
+		throw new ThemeConfigError('extend', 'must be a function.');
+	}
+
+	if (config.strict != null && typeof config.strict !== 'boolean') {
+		throw new ThemeConfigError('strict', 'must be a boolean.');
+	}
+
+	validateOverrideThemes(config.overrides, themeNamesOf(config as { themes?: object }));
+}
+
+export function themeNamesOf(config: { themes?: object }): string[] {
+	return ['light', 'dark', ...Object.keys(config.themes ?? {})];
+}

package/src/tokens/defaults.ts

@@ -1,52 +1,109 @@
-import type { SpacingTokens, RadiusTokens, ShadowTokens, ZIndexTokens } from '../types/tokens';
-
-export const DEFAULT_SPACING: SpacingTokens = {
-	xs: 4,
-	sm: 8,
-	md: 16,
-	lg: 24,
-	xl: 32,
-	xxl: 48,
-};
-
-export const DEFAULT_RADIUS: RadiusTokens = {
-	sm: 4,
-	md: 8,
-	lg: 16,
-	xl: 24,
-	full: 9999,
-};
+import { StyleSheet } from 'react-native';
+import { withAlpha } from '../color/parse';
+import type {
+	BorderWidthTokens,
+	MotionTokens,
+	OpacityTokens,
+	RadiusTokens,
+	ShadowTokens,
+	SizeTokens,
+	SpacingTokens,
+	ZIndexTokens,
+} from '../types/tokens';
 
-export function buildShadows(shadowColor: string): ShadowTokens {
+// Every builder returns a fresh object so no two themes share a reference
+// (spec AC-3.5, plan D-9).
+
+export function buildSpacing(): SpacingTokens {
 	return {
-		sm: {
-			shadowColor,
-			shadowOffset: { width: 0, height: 1 },
-			shadowOpacity: 0.12,
-			shadowRadius: 2,
-			elevation: 2,
-		},
-		md: {
-			shadowColor,
-			shadowOffset: { width: 0, height: 2 },
-			shadowOpacity: 0.16,
-			shadowRadius: 6,
-			elevation: 4,
-		},
-		lg: {
-			shadowColor,
-			shadowOffset: { width: 0, height: 4 },
-			shadowOpacity: 0.22,
-			shadowRadius: 12,
-			elevation: 8,
+		none: 0,
+		xxs: 2,
+		xs: 4,
+		sm: 8,
+		smPlus: 12,
+		md: 16,
+		mdPlus: 20,
+		lg: 24,
+		xl: 32,
+		xlPlus: 40,
+		xxl: 48,
+		xxxl: 64,
+	};
+}
+
+export function buildRadius(): RadiusTokens {
+	return { none: 0, xs: 2, sm: 4, md: 8, lg: 16, xl: 24, full: 9999 };
+}
+
+export function buildBorderWidth(): BorderWidthTokens {
+	return { hairline: StyleSheet.hairlineWidth, thin: 1, thick: 2 };
+}
+
+export function buildSize(): SizeTokens {
+	return { touchTarget: 44, icon: { sm: 16, md: 20, lg: 24 } };
+}
+
+export function buildOpacity(): OpacityTokens {
+	return {
+		hover: 0.08,
+		focus: 0.1,
+		pressed: 0.1,
+		dragged: 0.16,
+		disabledContent: 0.38,
+		disabledContainer: 0.12,
+	};
+}
+
+export function buildMotion(): MotionTokens {
+	return {
+		duration: { short: 100, medium: 250, long: 400 },
+		easing: {
+			standard: [0.2, 0, 0, 1],
+			emphasized: [0.05, 0.7, 0.1, 1],
+			decelerate: [0, 0, 0, 1],
+			accelerate: [0.3, 0, 1, 1],
 		},
 	};
 }
 
-export const DEFAULT_Z_INDEX: ZIndexTokens = {
-	base: 0,
-	raised: 10,
-	modal: 100,
-	overlay: 200,
-	toast: 300,
-};
+export function buildZIndex(): ZIndexTokens {
+	return { base: 0, raised: 10, modal: 100, overlay: 200, toast: 300 };
+}
+
+/** Material 3 elevation levels 1–3: a key shadow plus an ambient shadow. */
+const ELEVATION_LAYERS = {
+	sm: [
+		[1, 2, 0, 0.3],
+		[1, 3, 1, 0.15],
+	],
+	md: [
+		[1, 2, 0, 0.3],
+		[2, 6, 2, 0.15],
+	],
+	lg: [
+		[1, 3, 0, 0.3],
+		[4, 8, 3, 0.15],
+	],
+} as const;
+
+export function buildShadows(shadowColor: string): ShadowTokens {
+	const shadow = (layers: (typeof ELEVATION_LAYERS)[keyof typeof ELEVATION_LAYERS]) => ({
+		boxShadow: layers
+			.map(
+				([offsetY, blur, spread, alpha]) =>
+					`0px ${offsetY}px ${blur}px ${spread}px ${withAlpha(shadowColor, alpha)}`,
+			)
+			.join(', '),
+	});
+
+	return {
+		sm: shadow(ELEVATION_LAYERS.sm),
+		md: shadow(ELEVATION_LAYERS.md),
+		lg: shadow(ELEVATION_LAYERS.lg),
+	};
+}
+
+export const DEFAULT_MAX_FONT_SCALE = 2;
+
+/** Material 3 window size classes, in points. */
+export const DEFAULT_BREAKPOINTS = { compact: 0, medium: 600, expanded: 840 };