@chipmobilesdk/rn-theme 1.1.0 → 1.2.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @chipmobilesdk/rn-theme
 
+## 1.2.0
+
+### Minor Changes
+
+- An override that names a group the theme does not have is refused with a `ThemeConfigError` instead of being dropped. `overrides.light.radii` or `colors` had no effect and said nothing, which is exactly what the documented contract promised it would not do. The list of groups is derived from the generated theme, so a token group added later cannot be left out of it. ([#19](https://github.com/operationd8979/chip-mobile-sdk/pull/19))
+
+  A colour override now reaches everything derived from it. `color` is merged before `shadow` and `tone.neutral` are built, so pinning `color.onSurface` or `color.shadow` changes the neutral tone and the shadows too — they used to keep the generated value while the text presets followed the override, leaving a theme that disagreed with itself. The accent tones and `categorical` still come from the tonal palettes, which the README and the migration table now say.
+
+  A custom tone may not take a standard tone's name (`neutral`, `primary`, `info`, `success`, `warning`, `error`), and an `extend` that returns a group the theme already has (`spacing`, say) is refused: both used to replace the real thing at runtime, unvalidated, taking the contrast guarantees with them.
+
+  `createUnistylesConfig(undefined)` reports a `ThemeConfigError` with a path rather than a `TypeError`. `color.disabled` is derived from `opacity.disabledContent` rather than a second copy of the figure, and the vendored colour utilities no longer export a function nothing uses.
+
 ## 1.1.0
 
 ### Minor Changes
@@ -119,7 +131,7 @@ extension, and style presets. See `specs/014-rn-theme-v1/spec.md` in the source
 | `color.disabled` used as muted text | `color.onSurfaceVariant` or `text.bodyMuted` / `text.labelMuted` |
 | `color.disabled` for inactive UI | unchanged meaning; now `onSurface` at 38 % opacity, contrast-exempt |
 | `color.error`/`success`/`warning`/`info` as fills | `color.errorContainer` … with `onErrorContainer` …, or `tone.*.fill` / `onFill` |
-| `color.primary` equal to the brand hex | tone-mapped; override `color.primary` to pin a hex |
+| `color.primary` equal to the brand hex | tone-mapped; override `color.primary` to pin a hex (the accent tones and `categorical` stay on the palette) |
 | `shadow.md.shadowColor` … `elevation` | `shadow.md.boxShadow` |
 | App tokens spread into the theme + cast | `extend: ({ theme }) => ({ ... })` |
 | `overrides` adding unknown keys | rejected — use `extend` |

package/README.md

@@ -9,7 +9,6 @@ Native apps, configured for `react-native-unistyles` 3.
 
 - **Version**: see [CHANGELOG](CHANGELOG.md)
 - **Entrypoint**: `@chipmobilesdk/rn-theme`
-- **Demo**: `src/screens/ExampleScreen.tsx`
 
 ## Install
 
@@ -23,8 +22,9 @@ runtime dependency, no native code, and renders no components.
 ## Compatibility
 
 Validated in the ChipMobileSdk demo against React `19.2.3`, React Native `0.85.3`,
-React Native Unistyles `^3.2.5`, TypeScript `^5.8.3` and Node.js `>=22.11.0`, on Android and
-iOS. Shadows use React Native's cross-platform `boxShadow` (New Architecture).
+React Native Unistyles `^3.2.5`, TypeScript `^5.8.3` and Node.js `>=22.11.0`. **Android is
+device-validated; iOS is pending** (the package has no native code, and shadows use React
+Native's cross-platform `boxShadow` on the New Architecture).
 
 ## Setup Order
 
@@ -216,8 +216,17 @@ createUnistylesConfig({
 });
 ```
 
-Extensions may not reuse a base group name. Override keys must already exist — new tokens
-belong in `extend`.
+Extensions may not reuse a base group name, and a custom tone may not take a standard
+tone's name (`neutral`, `primary`, `info`, `success`, `warning`, `error`); both are
+refused with a `ThemeConfigError`. Override keys must already exist, at every level — a
+group the theme does not have, such as `radii` or `colors`, is refused rather than
+ignored. New tokens belong in `extend`.
+
+An override of `color.X` reaches everything derived from it: the text and surface presets,
+`shadow`, and `tone.neutral`, which is built from the neutral roles. The accent tones
+(`tone.primary` and the rest) and `categorical` come from the tonal palettes, so pinning
+`color.primary` to a hex does not change them — override `tone.primary` or the brand seed
+for that.
 
 ## Integrations
 
@@ -296,12 +305,6 @@ See the mapping table in `CHANGELOG.md` (`## 1.0.0`). In short: rename `typograp
 augmentation (`UnistylesThemeFromBrand`) with the one in *Setup Order*; move app tokens from
 spreads and casts into `extend`.
 
-## Release Validation
-
-```bash
-npm run validate
-```
-
 ## Semver and Migration
 
 - Patch: internal fix with no public shape or behaviour change.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@chipmobilesdk/rn-theme",
-	"version": "1.1.0",
+	"version": "1.2.0",
 	"private": false,
 	"license": "UNLICENSED",
 	"main": "src/index.ts",

package/src/color/roles.ts

@@ -7,6 +7,7 @@ import type {
 	StandardToneName,
 	ToneColors,
 } from '../types/colors';
+import { DEFAULT_OPACITY } from '../tokens/defaults';
 import { argbFromColor, hexFromArgb, withAlpha } from './parse';
 
 /**
@@ -27,7 +28,8 @@ 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;
+/** The same figure as `opacity.disabledContent`, from its one definition (THM-07). */
+export const DISABLED_CONTENT_OPACITY = DEFAULT_OPACITY.disabledContent;
 const SCRIM_OPACITY = 0.32;
 
 /**

package/src/theme/buildThemes.ts

@@ -27,8 +27,8 @@ import type {
 	Themes,
 } from '../types/theme';
 import type { FontToken, FontWeightName } from '../types/typography';
-import { describeFailures, ThemeContrastError } from './errors';
-import { mergeOverrides, pick } from './overrides';
+import { describeFailures, ThemeConfigError, ThemeContrastError } from './errors';
+import { isPlainObject, mergeOverrides, pick } from './overrides';
 import { validateThemeConfig } from './validateThemeConfig';
 
 export interface BuildThemesOptions {
@@ -56,23 +56,15 @@ function deviceHairlineWidth(): number {
 	return (result.ok ? result.module.StyleSheet?.hairlineWidth : undefined) ?? 1;
 }
 
-/** 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;
+/** The standard tone names an app's own tone may not take over (THM-03). */
+const STANDARD_TONES: ReadonlySet<string> = new Set([
+	'neutral',
+	'primary',
+	'info',
+	'success',
+	'warning',
+	'error',
+]);
 
 interface ThemeSource {
 	name: string;
@@ -92,6 +84,35 @@ function cloneFonts(font: Record<FontWeightName, FontToken>): Record<FontWeightN
 	return copy;
 }
 
+/**
+ * Every top-level group an override may name, and nothing else.
+ *
+ * An override naming a group that does not exist — `radii` for `radius`,
+ * `colors` for `color` — used to be dropped without a word, so the override
+ * simply had no effect (THM-01). The list is derived from what was generated
+ * rather than written out by hand, so a new token group cannot be forgotten
+ * (THM-06).
+ */
+function assertKnownOverrideGroups(
+	overrides: unknown,
+	known: Iterable<string>,
+	path: string,
+): void {
+	if (!isPlainObject(overrides)) {
+		return;
+	}
+	const allowed = new Set(known);
+	for (const key of Object.keys(overrides)) {
+		if (overrides[key] === undefined || allowed.has(key)) {
+			continue;
+		}
+		throw new ThemeConfigError(
+			`${path}.${key}`,
+			'does not exist on the theme. Add new tokens through `extend`.',
+		);
+	}
+}
+
 function buildOne(
 	source: ThemeSource,
 	fonts: ReturnType<typeof buildFonts>,
@@ -100,9 +121,15 @@ function buildOne(
 ): object {
 	const { name, scheme, config, palettes } = source;
 	const path = `overrides.${name}`;
-	const color = buildColorRoles(palettes, scheme);
+	const generatedColor = buildColorRoles(palettes, scheme);
+
+	// Colour is merged first, because what follows is derived from it: an
+	// override of `color.shadow` or `color.onSurface` used to leave `shadow` and
+	// `tone.neutral` built from the generated value, so a theme that pinned a
+	// colour disagreed with itself (THM-02).
+	const color = mergeOverrides(generatedColor, pick(overrides, ['color'])?.color, `${path}.color`);
 
-	const generated = {
+	const tokenGroups = {
 		color,
 		typography: buildTypography(config.typography, fonts.font, fonts.family),
 		font: cloneFonts(fonts.font),
@@ -117,21 +144,41 @@ function buildOne(
 		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);
+	} satisfies Omit<BaseTheme<string>, 'tone' | (typeof PRESET_KEYS)[number]>;
+
+	const tokenKeys = Object.keys(tokenGroups);
+	const tokens = mergeOverrides(tokenGroups, pick(overrides, tokenKeys), path);
 	const tone = mergeOverrides(
-		buildTones<string>(palettes, color, scheme),
+		// From the merged colour, so `tone.neutral` follows an override of
+		// `color.onSurface` as the text presets already did.
+		buildTones<string>(palettes, tokens.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>;
+	const base = { ...tokens, tone, ...presets } satisfies BaseTheme<string>;
 
 	if (!config.extend) {
+		assertKnownOverrideGroups(overrides, [...tokenKeys, 'tone', ...PRESET_KEYS], path);
 		return base;
 	}
 
 	const extension = config.extend({ name, scheme, theme: base });
+	for (const key of Object.keys(extension)) {
+		if (key in base) {
+			// `extend` returning `{ spacing: … }` replaced the whole spacing scale
+			// with whatever it held, unvalidated (THM-03).
+			throw new ThemeConfigError(
+				`extend.${key}`,
+				'is already a theme group. Give the extension token a name of its own.',
+			);
+		}
+	}
+	assertKnownOverrideGroups(
+		overrides,
+		[...tokenKeys, 'tone', ...PRESET_KEYS, ...Object.keys(extension)],
+		path,
+	);
 	const extensionOverrides = pick(overrides, Object.keys(extension));
 
 	return { ...base, ...mergeOverrides(extension, extensionOverrides, path) };
@@ -186,11 +233,22 @@ export function buildThemes<
 		{ name: 'light', scheme: 'light', config: loose, palettes: basePalettes },
 		{ name: 'dark', scheme: 'dark', config: loose, palettes: basePalettes },
 		...Object.entries(loose.themes ?? {}).map(([name, named]) => {
+			const tones = { ...loose.tones, ...named.tones } as Record<string, string>;
+			for (const tone of Object.keys(tones)) {
+				if (STANDARD_TONES.has(tone)) {
+					// A custom tone named `primary` silently replaced the standard
+					// one, contrast guarantees and all (THM-03).
+					throw new ThemeConfigError(
+						`themes.${name}.tones.${tone}`,
+						'is a standard tone. Override it through `overrides` instead.',
+					);
+				}
+			}
 			const namedConfig = {
 				...loose,
 				brandColors: named.brandColors ?? loose.brandColors,
 				seeds: { ...loose.seeds, ...named.seeds },
-				tones: { ...loose.tones, ...named.tones } as Record<string, string>,
+				tones,
 			};
 
 			return {

package/src/theme/validateThemeConfig.ts

@@ -36,6 +36,32 @@ function assertPositiveNumber(value: unknown, path: string): void {
 	}
 }
 
+/** The tones this package builds, which an app's own tone may not take over. */
+const STANDARD_TONE_NAMES: ReadonlySet<string> = new Set([
+	'neutral',
+	'primary',
+	'info',
+	'success',
+	'warning',
+	'error',
+]);
+
+function validateCustomTones(value: unknown, path: string): void {
+	if (value == null) {
+		return;
+	}
+	assertObject(value, path);
+	for (const name of Object.keys(value)) {
+		if (STANDARD_TONE_NAMES.has(name)) {
+			throw new ThemeConfigError(
+				`${path}.${name}`,
+				'is a standard tone; customise it through `overrides.<theme>.tone` instead.',
+			);
+		}
+	}
+	validateColorRecord(value, path);
+}
+
 function validateColorRecord(value: unknown, path: string, keys?: readonly string[]): void {
 	if (value == null) {
 		return;
@@ -134,7 +160,7 @@ function validateNamedThemes(value: unknown): void {
 		}
 
 		validateColorRecord(theme.seeds, `${path}.seeds`, SEED_KEYS);
-		validateColorRecord(theme.tones, `${path}.tones`);
+		validateCustomTones(theme.tones, `${path}.tones`);
 	}
 }
 
@@ -157,7 +183,7 @@ export function validateThemeConfig(config: unknown): void {
 	assertObject(config, 'config');
 	validateBrandColors(config.brandColors, 'brandColors');
 	validateColorRecord(config.seeds, 'seeds', SEED_KEYS);
-	validateColorRecord(config.tones, 'tones');
+	validateCustomTones(config.tones, 'tones');
 	validateTypography(config.typography);
 	validateNamedThemes(config.themes);
 

package/src/tokens/defaults.ts

@@ -43,15 +43,21 @@ export function buildSize(): SizeTokens {
 	return { touchTarget: 44, icon: { sm: 16, md: 20, lg: 24 } };
 }
 
+/**
+ * The opacity scale, as one definition. `color.disabled` is derived from
+ * `disabledContent` rather than from a second copy of 0.38 (THM-07).
+ */
+export const DEFAULT_OPACITY: OpacityTokens = {
+	hover: 0.08,
+	focus: 0.1,
+	pressed: 0.1,
+	dragged: 0.16,
+	disabledContent: 0.38,
+	disabledContainer: 0.12,
+};
+
 export function buildOpacity(): OpacityTokens {
-	return {
-		hover: 0.08,
-		focus: 0.1,
-		pressed: 0.1,
-		dragged: 0.16,
-		disabledContent: 0.38,
-		disabledContainer: 0.12,
-	};
+	return { ...DEFAULT_OPACITY };
 }
 
 export function buildMotion(): MotionTokens {

package/src/unistyles/createUnistylesConfig.ts

@@ -1,7 +1,7 @@
 import { buildThemes, type BuildThemesOptions } from '../theme/buildThemes';
 import { ThemeConfigError } from '../theme/errors';
 import { isPlainObject } from '../theme/overrides';
-import { themeNamesOf } from '../theme/validateThemeConfig';
+import { themeNamesOf, validateThemeConfig } from '../theme/validateThemeConfig';
 import { DEFAULT_BREAKPOINTS } from '../tokens/defaults';
 import type { EmptyExtension, ThemeConfig, ThemeName, Themes } from '../types/theme';
 
@@ -159,6 +159,9 @@ export function createUnistylesConfig<
 	config: ThemeConfig<TExt, TTone, TName>,
 	options?: UnistylesConfigOptions<NoInfer<TName>, TBreakpoints>,
 ): UnistylesConfig<TExt, TTone, TName, TBreakpoints> {
+	// The config first: reading `config.themes` for the theme names threw a
+	// TypeError with no path when the config itself was not an object (THM-10).
+	validateThemeConfig(config);
 	validateOptions(options, themeNamesOf(config));
 
 	return {

package/src/vendor/mcu/index.ts

@@ -2,4 +2,4 @@
 // imports from here only, so the vendored surface stays explicit.
 export { Hct } from './hct/hct';
 export { TonalPalette } from './palettes/tonal_palette';
-export { argbFromRgb, lstarFromArgb } from './utils/color_utils';
+export { argbFromRgb } from './utils/color_utils';