@chipmobilesdk/rn-theme 0.2.2 → 1.0.1

package/src/color/roles.ts

@@ -0,0 +1,262 @@
+import { Hct, TonalPalette } from '../vendor/mcu';
+import type { BrandColors, SeedColors } from '../types/brand';
+import type {
+	AccentRoleName,
+	ColorRoles,
+	ColorScheme,
+	StandardToneName,
+	ToneColors,
+} from '../types/colors';
+import { argbFromColor, hexFromArgb, withAlpha } from './parse';
+
+/**
+ * 0.2.x light semantic colours, kept as default seeds so their hues carry over.
+ */
+export const DEFAULT_SEEDS: Required<Omit<SeedColors, 'neutral'>> = {
+	error: '#B3261E',
+	success: '#2E7D32',
+	warning: '#E65100',
+	info: '#0277BD',
+};
+
+/** Neutral chroma when no neutral seed is given (Material 3 uses 4–8). */
+const NEUTRAL_CHROMA = 4;
+const NEUTRAL_VARIANT_CHROMA = 8;
+/** Upper bound for a supplied neutral seed, so surfaces never turn into a brand colour. */
+const MAX_NEUTRAL_SEED_CHROMA = 16;
+const NEUTRAL_VARIANT_EXTRA_CHROMA = 4;
+
+/** Material 3 opacities applied to `onSurface` and the scrim. */
+export const DISABLED_CONTENT_OPACITY = 0.38;
+const SCRIM_OPACITY = 0.32;
+
+/**
+ * Tones per role (plan D-3). Contrast depends only on tone, so these pairs
+ * hold for every hue and chroma.
+ */
+const TONES = {
+	light: {
+		role: 40,
+		onRole: 100,
+		container: 90,
+		onContainer: 10,
+		toneBorder: 50,
+		background: 98,
+		onBackground: 10,
+		surfaceVariant: 90,
+		onSurfaceVariant: 30,
+		surfaceContainerLowest: 100,
+		surfaceContainerLow: 96,
+		surfaceContainer: 94,
+		surfaceContainerHigh: 92,
+		surfaceContainerHighest: 90,
+		inverseSurface: 20,
+		inverseOnSurface: 95,
+		inversePrimary: 80,
+		outline: 50,
+		outlineVariant: 80,
+	},
+	dark: {
+		role: 80,
+		onRole: 20,
+		container: 30,
+		onContainer: 90,
+		toneBorder: 60,
+		background: 6,
+		onBackground: 90,
+		surfaceVariant: 30,
+		onSurfaceVariant: 80,
+		surfaceContainerLowest: 4,
+		surfaceContainerLow: 10,
+		surfaceContainer: 12,
+		surfaceContainerHigh: 17,
+		surfaceContainerHighest: 22,
+		inverseSurface: 90,
+		inverseOnSurface: 20,
+		inversePrimary: 40,
+		outline: 60,
+		outlineVariant: 30,
+	},
+} as const;
+
+const BLACK_TONE = 0;
+const KEY_TONE = 50;
+
+export interface PaletteInput {
+	brandColors: BrandColors;
+	seeds?: SeedColors;
+	tones?: Record<string, string>;
+}
+
+interface Palettes {
+	accent: Record<AccentRoleName, TonalPalette>;
+	neutral: TonalPalette;
+	neutralVariant: TonalPalette;
+	custom: Record<string, TonalPalette>;
+}
+
+/** Keeps the colour's hue and chroma (plan D-2). */
+function paletteOf(color: string): TonalPalette {
+	return TonalPalette.fromInt(argbFromColor(color));
+}
+
+/**
+ * Same tones as `TonalPalette.fromHueAndChroma`, without its key-colour search:
+ * a palette's tones depend only on hue and chroma, and these neutral chromas
+ * fit the gamut at tone 50, so no search is needed (spec FR-4).
+ */
+function paletteFromHueAndChroma(hue: number, chroma: number): TonalPalette {
+	return TonalPalette.fromHct(Hct.from(hue, chroma, KEY_TONE));
+}
+
+function neutralPalettes(input: PaletteInput): Pick<Palettes, 'neutral' | 'neutralVariant'> {
+	if (input.seeds?.neutral != null) {
+		const seed = Hct.fromInt(argbFromColor(input.seeds.neutral));
+		const chroma = Math.min(seed.chroma, MAX_NEUTRAL_SEED_CHROMA);
+
+		return {
+			neutral: paletteFromHueAndChroma(seed.hue, chroma),
+			neutralVariant: paletteFromHueAndChroma(seed.hue, chroma + NEUTRAL_VARIANT_EXTRA_CHROMA),
+		};
+	}
+
+	const hue = Hct.fromInt(argbFromColor(input.brandColors.primary)).hue;
+
+	return {
+		neutral: paletteFromHueAndChroma(hue, NEUTRAL_CHROMA),
+		neutralVariant: paletteFromHueAndChroma(hue, NEUTRAL_VARIANT_CHROMA),
+	};
+}
+
+export function buildPalettes(input: PaletteInput): Palettes {
+	const seeds = { ...DEFAULT_SEEDS, ...input.seeds };
+	const custom: Record<string, TonalPalette> = {};
+
+	for (const [name, color] of Object.entries(input.tones ?? {})) {
+		custom[name] = paletteOf(color);
+	}
+
+	return {
+		accent: {
+			primary: paletteOf(input.brandColors.primary),
+			secondary: paletteOf(input.brandColors.secondary),
+			tertiary: paletteOf(input.brandColors.tertiary),
+			error: paletteOf(seeds.error),
+			success: paletteOf(seeds.success),
+			warning: paletteOf(seeds.warning),
+			info: paletteOf(seeds.info),
+		},
+		...neutralPalettes(input),
+		custom,
+	};
+}
+
+function hex(palette: TonalPalette, tone: number): string {
+	return hexFromArgb(palette.tone(tone));
+}
+
+export function buildColorRoles(palettes: Palettes, scheme: ColorScheme): ColorRoles {
+	const t = TONES[scheme];
+	const { neutral, neutralVariant } = palettes;
+	const accent = (palette: TonalPalette) => ({
+		role: hex(palette, t.role),
+		onRole: hex(palette, t.onRole),
+		container: hex(palette, t.container),
+		onContainer: hex(palette, t.onContainer),
+	});
+	const [primary, secondary, tertiary, error, success, warning, info] = (
+		['primary', 'secondary', 'tertiary', 'error', 'success', 'warning', 'info'] as const
+	).map(name => accent(palettes.accent[name]));
+	const onSurface = hex(neutral, t.onBackground);
+
+	return {
+		primary: primary.role,
+		onPrimary: primary.onRole,
+		primaryContainer: primary.container,
+		onPrimaryContainer: primary.onContainer,
+		secondary: secondary.role,
+		onSecondary: secondary.onRole,
+		secondaryContainer: secondary.container,
+		onSecondaryContainer: secondary.onContainer,
+		tertiary: tertiary.role,
+		onTertiary: tertiary.onRole,
+		tertiaryContainer: tertiary.container,
+		onTertiaryContainer: tertiary.onContainer,
+		error: error.role,
+		onError: error.onRole,
+		errorContainer: error.container,
+		onErrorContainer: error.onContainer,
+		success: success.role,
+		onSuccess: success.onRole,
+		successContainer: success.container,
+		onSuccessContainer: success.onContainer,
+		warning: warning.role,
+		onWarning: warning.onRole,
+		warningContainer: warning.container,
+		onWarningContainer: warning.onContainer,
+		info: info.role,
+		onInfo: info.onRole,
+		infoContainer: info.container,
+		onInfoContainer: info.onContainer,
+		background: hex(neutral, t.background),
+		onBackground: onSurface,
+		surface: hex(neutral, t.background),
+		onSurface,
+		surfaceVariant: hex(neutralVariant, t.surfaceVariant),
+		onSurfaceVariant: hex(neutralVariant, t.onSurfaceVariant),
+		surfaceContainerLowest: hex(neutral, t.surfaceContainerLowest),
+		surfaceContainerLow: hex(neutral, t.surfaceContainerLow),
+		surfaceContainer: hex(neutral, t.surfaceContainer),
+		surfaceContainerHigh: hex(neutral, t.surfaceContainerHigh),
+		surfaceContainerHighest: hex(neutral, t.surfaceContainerHighest),
+		inverseSurface: hex(neutral, t.inverseSurface),
+		inverseOnSurface: hex(neutral, t.inverseOnSurface),
+		inversePrimary: hex(palettes.accent.primary, t.inversePrimary),
+		outline: hex(neutralVariant, t.outline),
+		outlineVariant: hex(neutralVariant, t.outlineVariant),
+		scrim: withAlpha(hex(neutral, BLACK_TONE), SCRIM_OPACITY),
+		shadow: hex(neutral, BLACK_TONE),
+		disabled: withAlpha(onSurface, DISABLED_CONTENT_OPACITY),
+	};
+}
+
+function accentTone(palette: TonalPalette, scheme: ColorScheme): ToneColors {
+	const t = TONES[scheme];
+
+	return {
+		fg: hex(palette, t.role),
+		container: hex(palette, t.container),
+		onContainer: hex(palette, t.onContainer),
+		border: hex(palette, t.toneBorder),
+		fill: hex(palette, t.role),
+		onFill: hex(palette, t.onRole),
+	};
+}
+
+export function buildTones<TTone extends string>(
+	palettes: Palettes,
+	color: ColorRoles,
+	scheme: ColorScheme,
+): Record<StandardToneName | TTone, ToneColors> {
+	const tones: Record<string, ToneColors> = {
+		neutral: {
+			fg: color.onSurface,
+			container: color.surfaceContainerHigh,
+			onContainer: color.onSurface,
+			border: color.outline,
+			fill: color.inverseSurface,
+			onFill: color.inverseOnSurface,
+		},
+		primary: accentTone(palettes.accent.primary, scheme),
+		info: accentTone(palettes.accent.info, scheme),
+		success: accentTone(palettes.accent.success, scheme),
+		warning: accentTone(palettes.accent.warning, scheme),
+		error: accentTone(palettes.accent.error, scheme),
+	};
+
+	for (const [name, palette] of Object.entries(palettes.custom)) {
+		tones[name] = accentTone(palette, scheme);
+	}
+
+	return tones as Record<StandardToneName | TTone, ToneColors>;
+}

package/src/index.ts

@@ -1,24 +1,27 @@
-// ─── Color utilities (advanced use / custom palette overrides) ──────────────
-export { generateLightPalette, generateDarkPalette } from './utils/colorGeneration';
+// ─── Theme building ─────────────────────────────────────────────────────────
+export { buildThemes } from './theme/buildThemes';
+export type { BuildThemesOptions } from './theme/buildThemes';
+export { ThemeConfigError, ThemeContrastError } from './theme/errors';
 
-// ─── Unistyles helpers ──────────────────────────────────────────────────────
+// ─── Unistyles ──────────────────────────────────────────────────────────────
 export { createUnistylesConfig } from './unistyles/createUnistylesConfig';
-export type {
-	UnistylesThemes,
-	UnistylesConfigOptions,
-	UnistylesConfig,
-} from './unistyles/createUnistylesConfig';
-export type { UnistylesThemeFromBrand } from './unistyles/types';
+export type { UnistylesConfig, UnistylesConfigOptions } from './unistyles/createUnistylesConfig';
+export { applyThemeMode } from './unistyles/themeMode';
+export type { ThemeMode, ThemeModeRuntime } from './unistyles/themeMode';
+export { DEFAULT_BREAKPOINTS } from './tokens/defaults';
+
+// ─── Colour utilities ───────────────────────────────────────────────────────
+export { auditTheme, contrastRatio } from './color/contrast';
+export type { ContrastFailure } from './color/contrast';
+export { withAlpha } from './color/parse';
+
+// ─── Style presets ──────────────────────────────────────────────────────────
+export { layout, presets } from './presets/layout';
+export { byTone } from './presets/byTone';
+
+// ─── Integrations ───────────────────────────────────────────────────────────
+export { toNavigationTheme } from './integration/navigationTheme';
+export type { NavigationTheme } from './integration/navigationTheme';
 
 // ─── Types ──────────────────────────────────────────────────────────────────
-export type { BrandColors } from './types/brand';
-export type { ThemeColors } from './types/colors';
-export type { TypographyConfig, TypographyToken, Typography } from './types/typography';
-export type {
-	SpacingTokens,
-	RadiusTokens,
-	ShadowToken,
-	ShadowTokens,
-	ZIndexTokens,
-} from './types/tokens';
-export type { DeepPartial, StyleConfig, StyleTheme } from './types/style';
+export type * from './types';

package/src/integration/navigationTheme.ts

@@ -0,0 +1,51 @@
+import type { ColorRoles, ColorScheme } from '../types/colors';
+import type { FontToken, FontWeightName } from '../types/typography';
+
+/**
+ * The theme shape React Navigation expects, declared here so the package needs
+ * no navigation dependency (spec AC-9.3).
+ */
+export interface NavigationTheme {
+	dark: boolean;
+	colors: {
+		primary: string;
+		background: string;
+		card: string;
+		text: string;
+		border: string;
+		notification: string;
+	};
+	fonts: {
+		regular: FontToken;
+		medium: FontToken;
+		bold: FontToken;
+		heavy: FontToken;
+	};
+}
+
+interface NavigationSource {
+	color: ColorRoles;
+	font: Record<FontWeightName, FontToken>;
+}
+
+export function toNavigationTheme(theme: NavigationSource, scheme: ColorScheme): NavigationTheme {
+	const { color, font } = theme;
+
+	return {
+		dark: scheme === 'dark',
+		colors: {
+			primary: color.primary,
+			background: color.background,
+			card: color.surfaceContainer,
+			text: color.onSurface,
+			border: color.outlineVariant,
+			notification: color.error,
+		},
+		fonts: {
+			regular: { ...font.regular },
+			medium: { ...font.medium },
+			bold: { ...font.bold },
+			heavy: { ...font.heavy },
+		},
+	};
+}

package/src/presets/byTone.ts

@@ -0,0 +1,28 @@
+import type { ToneColors } from '../types/colors';
+
+/**
+ * Builds a variant map with one entry per tone of the theme.
+ *
+ * Call it inline under a literal `variants` key, with the stylesheet's own
+ * `theme` argument:
+ *
+ * ```ts
+ * toneText: { variants: { tone: byTone(theme, t => ({ color: t.onContainer })) } },
+ * ```
+ *
+ * The Unistyles Babel plugin reads dependencies statically: a variants object
+ * built elsewhere, or a `theme` read through an alias, hides them and the
+ * style stops updating on theme or variant changes.
+ */
+export function byTone<TTheme extends { tone: Record<string, ToneColors> }, TStyle>(
+	theme: TTheme,
+	build: (tone: ToneColors, name: keyof TTheme['tone'] & string) => TStyle,
+): Record<keyof TTheme['tone'] & string, TStyle> {
+	const result = {} as Record<keyof TTheme['tone'] & string, TStyle>;
+
+	for (const name of Object.keys(theme.tone) as Array<keyof TTheme['tone'] & string>) {
+		result[name] = build(theme.tone[name], name);
+	}
+
+	return result;
+}

package/src/presets/layout.ts

@@ -0,0 +1,38 @@
+import type { TextStyle, ViewStyle } from 'react-native';
+
+/**
+ * Theme-independent flex presets. Spread them inside `StyleSheet.create` or
+ * put them in a style array; styles built only from these carry no theme
+ * dependency, so Unistyles never recalculates them on a theme change.
+ */
+export const layout = {
+	row: { flexDirection: 'row' },
+	column: { flexDirection: 'column' },
+	rowCenter: { flexDirection: 'row', alignItems: 'center' },
+	rowBetween: { flexDirection: 'row', alignItems: 'center', justifyContent: 'space-between' },
+	center: { alignItems: 'center', justifyContent: 'center' },
+	fill: { flex: 1 },
+	wrap: { flexDirection: 'row', flexWrap: 'wrap' },
+	absoluteFill: { position: 'absolute', top: 0, right: 0, bottom: 0, left: 0 },
+	selfStart: { alignSelf: 'flex-start' },
+	selfCenter: { alignSelf: 'center' },
+	selfEnd: { alignSelf: 'flex-end' },
+} as const satisfies Record<string, ViewStyle>;
+
+interface TextPresetsStatic {
+	/**
+	 * For a `Text` used as an icon: Android sizes text boxes from asymmetric
+	 * font metrics, so a centred glyph sits high or low beside a label unless
+	 * font padding is removed and the glyph centred in its box. iOS ignores both.
+	 */
+	glyphAlign: Pick<TextStyle, 'includeFontPadding' | 'textAlignVertical'>;
+	/** Equal-width digits, so columns of times or amounts do not jitter. */
+	tabularNums: Pick<TextStyle, 'fontVariant'>;
+}
+
+// Annotated rather than `as const`: a readonly `fontVariant` tuple fails
+// React Native's `TextStyle` and degrades inference of sibling styles (spec AC-3.7).
+export const presets: TextPresetsStatic = {
+	glyphAlign: { includeFontPadding: false, textAlignVertical: 'center' },
+	tabularNums: { fontVariant: ['tabular-nums'] },
+};

package/src/presets/themePresets.ts

@@ -0,0 +1,101 @@
+import type { ColorRoles } from '../types/colors';
+import type {
+	BaseTheme,
+	BorderPresets,
+	BoxPresets,
+	InlinePreset,
+	StackPreset,
+	TextPreset,
+	TextPresets,
+} from '../types/theme';
+import type { SpacingKey } from '../types/tokens';
+import type { TypographyToken } from '../types/typography';
+
+type PresetKey = 'text' | 'stack' | 'inline' | 'border' | 'box';
+type TokenSource = Omit<BaseTheme, PresetKey | 'tone'>;
+
+export const PRESET_KEYS: readonly PresetKey[] = ['text', 'stack', 'inline', 'border', 'box'];
+
+function textPreset(token: TypographyToken, color: string): TextPreset {
+	return { ...token, color };
+}
+
+function buildText({ typography }: TokenSource, color: ColorRoles): TextPresets {
+	return {
+		body: textPreset(typography.body, color.onSurface),
+		bodyMuted: textPreset(typography.body, color.onSurfaceVariant),
+		label: textPreset(typography.label, color.onSurface),
+		labelMuted: textPreset(typography.label, color.onSurfaceVariant),
+		caption: textPreset(typography.caption, color.onSurfaceVariant),
+		title: textPreset(typography.title, color.onSurface),
+		headline: textPreset(typography.headline, color.onSurface),
+		disabled: textPreset(typography.body, color.disabled),
+	};
+}
+
+function bySpacing<T>(spacing: TokenSource['spacing'], build: (gap: number) => T) {
+	const result = {} as Record<SpacingKey, T>;
+
+	for (const key of Object.keys(spacing) as SpacingKey[]) {
+		result[key] = build(spacing[key]);
+	}
+
+	return result;
+}
+
+function buildBorder({ borderWidth, color }: TokenSource): BorderPresets {
+	return {
+		hairline: { borderWidth: borderWidth.hairline, borderColor: color.outlineVariant },
+		top: { borderTopWidth: borderWidth.thin, borderTopColor: color.outlineVariant },
+		bottom: { borderBottomWidth: borderWidth.thin, borderBottomColor: color.outlineVariant },
+		all: { borderWidth: borderWidth.thin, borderColor: color.outline },
+	};
+}
+
+function buildBox({ borderWidth, color, radius, spacing, size }: TokenSource): BoxPresets {
+	return {
+		outlined: {
+			borderWidth: borderWidth.thin,
+			borderColor: color.outline,
+			borderRadius: radius.md,
+			padding: spacing.sm,
+			gap: spacing.xs,
+		},
+		card: {
+			backgroundColor: color.surfaceContainerLow,
+			borderRadius: radius.lg,
+			padding: spacing.md,
+			gap: spacing.sm,
+		},
+		sheet: {
+			backgroundColor: color.surfaceContainerLow,
+			borderTopLeftRadius: radius.xl,
+			borderTopRightRadius: radius.xl,
+			padding: spacing.md,
+			gap: spacing.md,
+		},
+		touchTarget: {
+			minWidth: size.touchTarget,
+			minHeight: size.touchTarget,
+			justifyContent: 'center',
+		},
+	};
+}
+
+/**
+ * Token-reading presets, built from the theme's final (overridden) tokens so
+ * they follow every override — e.g. `radius.md = 0` reaches `box.outlined`.
+ */
+export function buildPresets(tokens: TokenSource): Pick<BaseTheme, PresetKey> {
+	return {
+		text: buildText(tokens, tokens.color),
+		stack: bySpacing<StackPreset>(tokens.spacing, gap => ({ flexDirection: 'column', gap })),
+		inline: bySpacing<InlinePreset>(tokens.spacing, gap => ({
+			flexDirection: 'row',
+			alignItems: 'center',
+			gap,
+		})),
+		border: buildBorder(tokens),
+		box: buildBox(tokens),
+	};
+}