@idealyst/theme 1.2.101 → 1.2.103

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@idealyst/theme",
-  "version": "1.2.101",
+  "version": "1.2.103",
   "description": "Theming system for Idealyst Framework",
   "readme": "README.md",
   "main": "src/index.ts",
@@ -63,7 +63,7 @@
     "publish:npm": "npm publish"
   },
   "dependencies": {
-    "@idealyst/tooling": "^1.2.101"
+    "@idealyst/tooling": "^1.2.103"
   },
   "peerDependencies": {
     "react-native-unistyles": ">=3.0.0"

package/src/babel/plugin.js

@@ -66,10 +66,18 @@ function getOrCreateEntry(componentName) {
 // AST Deep Merge - Merges style object ASTs at build time
 // ============================================================================
 
+// Platform-specific keys used by Unistyles
+const PLATFORM_KEYS = new Set(['_web', '_ios', '_android']);
+
 /**
  * Deep merge two ObjectExpression ASTs.
  * Source properties override target properties.
  * Nested objects are recursively merged.
+ *
+ * Also propagates extension properties into platform-specific blocks (_web, _ios, _android)
+ * when those blocks already contain the same key. This ensures that e.g. setting
+ * `fontFamily: 'MyFont'` in an extension properly overrides `_web: { fontFamily: 'inherit' }`
+ * in the base styles.
  */
 function mergeObjectExpressions(t, target, source) {
     if (!t.isObjectExpression(target) || !t.isObjectExpression(source)) {
@@ -90,6 +98,9 @@ function mergeObjectExpressions(t, target, source) {
 
     const resultProps = [...target.properties];
 
+    // Collect non-platform source property keys and values for propagation
+    const sourceNonPlatformProps = new Map();
+
     for (const prop of source.properties) {
         if (!t.isObjectProperty(prop)) continue;
 
@@ -97,6 +108,10 @@ function mergeObjectExpressions(t, target, source) {
                     t.isStringLiteral(prop.key) ? prop.key.value : null;
         if (!key) continue;
 
+        if (!PLATFORM_KEYS.has(key)) {
+            sourceNonPlatformProps.set(key, prop);
+        }
+
         const existingProp = targetProps.get(key);
 
         if (existingProp) {
@@ -128,6 +143,48 @@ function mergeObjectExpressions(t, target, source) {
         }
     }
 
+    // Propagate extension properties into platform-specific blocks.
+    // If the base has _web: { fontFamily: 'inherit' } and the extension sets
+    // fontFamily: 'MyFont' at the top level, we need to also override fontFamily
+    // inside the _web block so the platform-specific value doesn't shadow the extension.
+    if (sourceNonPlatformProps.size > 0) {
+        for (let i = 0; i < resultProps.length; i++) {
+            const prop = resultProps[i];
+            if (!t.isObjectProperty(prop)) continue;
+
+            const key = t.isIdentifier(prop.key) ? prop.key.name :
+                        t.isStringLiteral(prop.key) ? prop.key.value : null;
+            if (!key || !PLATFORM_KEYS.has(key)) continue;
+            if (!t.isObjectExpression(prop.value)) continue;
+
+            // Check if any source properties conflict with keys in this platform block
+            const platformProps = prop.value.properties;
+            let modified = false;
+            const newPlatformProps = [...platformProps];
+
+            for (let j = 0; j < newPlatformProps.length; j++) {
+                const platProp = newPlatformProps[j];
+                if (!t.isObjectProperty(platProp)) continue;
+
+                const platKey = t.isIdentifier(platProp.key) ? platProp.key.name :
+                                t.isStringLiteral(platProp.key) ? platProp.key.value : null;
+                if (!platKey) continue;
+
+                const extProp = sourceNonPlatformProps.get(platKey);
+                if (extProp) {
+                    // Extension has a property that conflicts with this platform block key.
+                    // Override the platform block value with the extension value.
+                    newPlatformProps[j] = t.objectProperty(platProp.key, t.cloneDeep(extProp.value));
+                    modified = true;
+                }
+            }
+
+            if (modified) {
+                resultProps[i] = t.objectProperty(prop.key, t.objectExpression(newPlatformProps));
+            }
+        }
+    }
+
     return t.objectExpression(resultProps);
 }
 
@@ -873,7 +930,10 @@ module.exports = function idealystStylesPlugin({ types: t }) {
                     opts.processAll ||
                     (opts.autoProcessPaths?.some(p => filename.includes(p)));
 
-                if (!shouldProcess) return;
+                // extendStyle/overrideStyle must ALWAYS be processed regardless of
+                // shouldProcess, since they are called from user code (not just from
+                // @idealyst/* packages). Only defineStyle and StyleSheet.create
+                // $iterator expansion are gated by autoProcessPaths.
 
                 // ============================================================
                 // Handle extendStyle - Store extension AST for later merging
@@ -965,6 +1025,10 @@ module.exports = function idealystStylesPlugin({ types: t }) {
                     return;
                 }
 
+                // defineStyle and StyleSheet.create are only processed for files
+                // matching autoProcessPaths (i.e., framework packages)
+                if (!shouldProcess) return;
+
                 // ============================================================
                 // Handle defineStyle - Merge with extensions and output StyleSheet.create
                 // ============================================================

package/src/colorScheme.ts

@@ -1,10 +1,71 @@
-import { UnistylesRuntime } from 'react-native-unistyles';
+import { StyleSheet, UnistylesRuntime } from 'react-native-unistyles';
+import type { UnistylesThemes } from 'react-native-unistyles';
+import type { BuiltTheme } from './builder';
 
 /**
  * Color scheme preference type.
  */
 export type ColorScheme = 'light' | 'dark';
 
+/**
+ * Any theme produced by the builder system (fromTheme().build() or createTheme().build()).
+ */
+type AnyBuiltTheme = BuiltTheme<string, string, string, string, string, string, string, string, string>;
+
+/**
+ * Options for configureThemes().
+ */
+export interface ConfigureThemesOptions {
+    /**
+     * Theme instances keyed by name. Must include at least `light` and `dark`.
+     *
+     * @example
+     * ```typescript
+     * { light: customLightTheme, dark: customDarkTheme }
+     * ```
+     */
+    themes: { light: AnyBuiltTheme; dark: AnyBuiltTheme } & Record<string, AnyBuiltTheme>;
+
+    /**
+     * Which theme to activate on startup (default: 'light').
+     */
+    initialTheme?: string;
+}
+
+/**
+ * Configure the theme system. Call this **once** at app startup,
+ * before any component renders.
+ *
+ * This replaces the need to import `StyleSheet` from `react-native-unistyles` directly.
+ *
+ * @example
+ * ```typescript
+ * import { configureThemes, lightTheme, darkTheme, fromTheme } from '@idealyst/theme';
+ *
+ * const light = fromTheme(lightTheme).build();
+ * const dark  = fromTheme(darkTheme).build();
+ *
+ * configureThemes({ themes: { light, dark } });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With a custom initial theme
+ * configureThemes({
+ *   themes: { light, dark, midnight },
+ *   initialTheme: 'midnight',
+ * });
+ * ```
+ */
+export function configureThemes(options: ConfigureThemesOptions): void {
+    StyleSheet.configure({
+        themes: options.themes as Record<string, object> as UnistylesThemes,
+        settings: {
+            initialTheme: (options.initialTheme ?? 'light') as keyof UnistylesThemes,
+        },
+    });
+}
+
 /**
  * Get the current system/device color scheme preference.
  *
@@ -27,19 +88,21 @@ export function getColorScheme(): ColorScheme | null {
 }
 
 /**
- * Theme settings controller - wraps Unistyles runtime for theme management.
+ * Theme settings controller — wraps Unistyles runtime for theme management.
+ *
+ * Use this instead of importing `UnistylesRuntime` directly.
  */
 export const ThemeSettings = {
     /**
      * Set the active theme by name with content color scheme.
      *
-     * @param themeName - The theme name to activate
+     * @param themeName - The theme name to activate (e.g. 'light', 'dark')
      * @param contentColor - The content color scheme ('light' or 'dark')
      * @param animated - Whether to animate the status bar transition (default: false)
      *
      * @example
      * ```typescript
-     * ThemeSettings.setTheme('darkBlue', 'dark');
+     * ThemeSettings.setTheme('dark', 'dark');
      * ThemeSettings.setTheme('light', 'light', true); // animated
      * ```
      */
@@ -50,4 +113,36 @@ export const ThemeSettings = {
         );
         UnistylesRuntime.statusBar.setStyle((contentColor === 'dark' ? 'light' : 'dark') as any, animated);
     },
+
+    /**
+     * Get the name of the currently active theme.
+     *
+     * @returns The current theme name (e.g. 'light', 'dark')
+     *
+     * @example
+     * ```typescript
+     * const current = ThemeSettings.getThemeName(); // 'dark'
+     * ```
+     */
+    getThemeName(): string {
+        return String(UnistylesRuntime.themeName);
+    },
+
+    /**
+     * Enable or disable adaptive (system-following) themes.
+     *
+     * When enabled, the theme automatically switches to match the device's
+     * light/dark mode setting.
+     *
+     * @param enabled - Whether to follow the system theme
+     *
+     * @example
+     * ```typescript
+     * ThemeSettings.setAdaptiveThemes(true);  // follow system
+     * ThemeSettings.setAdaptiveThemes(false); // manual control
+     * ```
+     */
+    setAdaptiveThemes(enabled: boolean): void {
+        UnistylesRuntime.setAdaptiveThemes(enabled);
+    },
 };

package/src/defaults.ts

@@ -0,0 +1,33 @@
+/**
+ * Global component defaults.
+ *
+ * These values are used as fallbacks when neither the component prop
+ * nor a component-specific default is set.
+ * Call the setter once at app startup (e.g., in App.tsx).
+ *
+ * @example
+ * ```typescript
+ * import { setDefaultMaxFontSizeMultiplier } from '@idealyst/theme';
+ *
+ * setDefaultMaxFontSizeMultiplier(1.5);
+ * ```
+ */
+
+let _defaultMaxFontSizeMultiplier: number | undefined = undefined;
+
+/**
+ * Set the global default `maxFontSizeMultiplier` for all text-rendering components.
+ * Any component without an explicit prop or component-level default will use this value.
+ * Pass `undefined` to clear (no limit).
+ */
+export function setDefaultMaxFontSizeMultiplier(value: number | undefined): void {
+    _defaultMaxFontSizeMultiplier = value;
+}
+
+/**
+ * Get the current global default `maxFontSizeMultiplier`.
+ * Returns `undefined` if no default has been set.
+ */
+export function getDefaultMaxFontSizeMultiplier(): number | undefined {
+    return _defaultMaxFontSizeMultiplier;
+}

package/src/index.ts

@@ -41,6 +41,9 @@ export { useStyleProps, type StyleProps } from './useStyleProps';
 // Shadow utility (platform-specific via .native.ts)
 export { shadow, type ShadowOptions, type ShadowStyle } from './shadow';
 
+// Component defaults
+export { setDefaultMaxFontSizeMultiplier, getDefaultMaxFontSizeMultiplier } from './defaults';
+
 // Animation tokens and utilities
 // Note: Use '@idealyst/theme/animation' for full animation API
 export { durations, easings, presets } from './animation/tokens';

package/src/theme/extensions.ts

@@ -15,7 +15,6 @@ export interface DefaultTheme {
         surface: Record<string, ColorValue>;
         text: Record<string, ColorValue>;
         border: Record<string, ColorValue>;
-        card: Record<string, ColorValue>;
     };
     sizes: {
         button: Record<string, ButtonSizeValue>;