@idealyst/theme 1.2.102 → 1.2.104

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@idealyst/theme",
-  "version": "1.2.102",
+  "version": "1.2.104",
   "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.102"
+    "@idealyst/tooling": "^1.2.104"
   },
   "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) {
@@ -111,11 +126,42 @@ function mergeObjectExpressions(t, target, source) {
                 const idx = resultProps.indexOf(existingProp);
                 resultProps[idx] = t.objectProperty(existingProp.key, mergedValue);
             }
-            // If both are arrow functions (dynamic styles), merge their return values
-            else if (t.isArrowFunctionExpression(existingValue) && t.isArrowFunctionExpression(newValue)) {
-                const mergedFn = mergeDynamicStyleFunctions(t, existingValue, newValue);
-                const idx = resultProps.indexOf(existingProp);
-                resultProps[idx] = t.objectProperty(existingProp.key, mergedFn);
+            // If base is a dynamic function and extension is anything (plain object
+            // or arrow function), extract the extension's object and merge it into the
+            // base function's return body. Extensions should only provide plain objects,
+            // but if a function is given we unwrap its body to get the object.
+            else if (t.isArrowFunctionExpression(existingValue)) {
+                let extObj = newValue;
+                // If extension mistakenly provides a function, unwrap its return body
+                if (t.isArrowFunctionExpression(extObj)) {
+                    extObj = extObj.body;
+                    if (t.isParenthesizedExpression(extObj)) {
+                        extObj = extObj.expression;
+                    }
+                }
+
+                if (t.isObjectExpression(extObj)) {
+                    let baseBody = existingValue.body;
+                    if (t.isParenthesizedExpression(baseBody)) {
+                        baseBody = baseBody.expression;
+                    }
+                    if (t.isObjectExpression(baseBody)) {
+                        const mergedBody = mergeObjectExpressions(t, baseBody, extObj);
+                        const idx = resultProps.indexOf(existingProp);
+                        resultProps[idx] = t.objectProperty(
+                            existingProp.key,
+                            t.arrowFunctionExpression(existingValue.params, mergedBody)
+                        );
+                    } else {
+                        // Block body or other complex form — fall back to replacement
+                        const idx = resultProps.indexOf(existingProp);
+                        resultProps[idx] = prop;
+                    }
+                } else {
+                    // Extension body isn't an object — fall back to replacement
+                    const idx = resultProps.indexOf(existingProp);
+                    resultProps[idx] = prop;
+                }
             }
             // Otherwise, source replaces target
             else {
@@ -128,34 +174,49 @@ function mergeObjectExpressions(t, target, source) {
         }
     }
 
-    return t.objectExpression(resultProps);
-}
-
-/**
- * Merge two dynamic style functions (arrow functions that return style objects).
- * Creates a new function that merges both return values.
- */
-function mergeDynamicStyleFunctions(t, baseFn, extFn) {
-    // Get the bodies (assuming they return ObjectExpressions)
-    let baseBody = baseFn.body;
-    let extBody = extFn.body;
+    // 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;
 
-    // Handle parenthesized expressions
-    if (t.isParenthesizedExpression(baseBody)) {
-        baseBody = baseBody.expression;
-    }
-    if (t.isParenthesizedExpression(extBody)) {
-        extBody = extBody.expression;
-    }
+            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 both return ObjectExpressions directly, merge them
-    if (t.isObjectExpression(baseBody) && t.isObjectExpression(extBody)) {
-        const mergedBody = mergeObjectExpressions(t, baseBody, extBody);
-        return t.arrowFunctionExpression(baseFn.params, mergedBody);
+            if (modified) {
+                resultProps[i] = t.objectProperty(prop.key, t.objectExpression(newPlatformProps));
+            }
+        }
     }
 
-    // For block statements, this is more complex - just use extension for now
-    return extFn;
+    return t.objectExpression(resultProps);
 }
 
 /**
@@ -873,7 +934,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 +1029,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/componentStyles.ts

@@ -22,10 +22,12 @@ import type { TextStyle, ViewStyle } from 'react-native';
 /**
  * Registry interface that components augment to register their style types.
  * This enables type-safe extendStyle and overrideStyle calls.
+ *
+ * Style definitions must use plain style objects, not functions.
  */
 export interface ComponentStyleRegistry {
   // Components augment this interface to add their style types
-  // Example: Text: { text: (params: TextStyleParams) => TextStyleObject }
+  // Example: Text: { text: TextStyle & { variants?: { ... } } }
 }
 
 /**
@@ -37,38 +39,25 @@ export type ComponentStyleDef<K extends string> = K extends keyof ComponentStyle
   : Record<string, any>;
 
 /**
- * Deep partial type that works with functions.
- * For style functions, preserves the function signature but makes the return type partial.
+ * Deep partial type for style objects.
+ * Recursively makes all properties optional.
+ * Extensions must be plain style objects — functions are not supported.
  */
-export type DeepPartialStyle<T> = T extends (...args: infer A) => infer R
-  ? (...args: A) => DeepPartialStyle<R>
-  : T extends object
-    ? { [K in keyof T]?: DeepPartialStyle<T[K]> }
-    : T;
+export type DeepPartialStyle<T> = T extends object
+  ? { [K in keyof T]?: DeepPartialStyle<T[K]> }
+  : T;
 
 /**
- * Style definition for extendStyle - requires functions with same params as base.
- * All style properties must be functions to access dynamic params.
+ * Style definition for extendStyle - plain style objects only.
+ * Functions are not supported; the babel plugin merges plain objects into base styles.
  */
 export type ExtendStyleDef<K extends string> = DeepPartialStyle<ComponentStyleDef<K>>;
 
 /**
- * Style definition for overrideStyle - requires full implementation with functions.
+ * Style definition for overrideStyle - requires full style implementation.
  */
 export type OverrideStyleDef<K extends string> = ComponentStyleDef<K>;
 
-/**
- * Helper to extract the params type from a dynamic style function.
- * Use this to type your extension functions.
- *
- * @example
- * ```typescript
- * type TextParams = StyleParams<TextStyleDef['text']>;
- * // TextParams = { color?: TextColorVariant }
- * ```
- */
-export type StyleParams<T> = T extends (params: infer P) => any ? P : never;
-
 // =============================================================================
 // Common Style Types
 // =============================================================================
@@ -86,8 +75,3 @@ export interface StyleWithVariants<TVariants extends Record<string, any> = Recor
     [K in keyof TVariants]?: TVariants[K];
   } & { styles: ViewStyle | TextStyle }>;
 }
-
-/**
- * Dynamic style function type.
- */
-export type DynamicStyleFn<TParams, TStyle> = (params: TParams) => TStyle;

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>;