@idealyst/theme 1.2.100 → 1.2.101

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@idealyst/theme",
-  "version": "1.2.100",
+  "version": "1.2.101",
   "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.100"
+    "@idealyst/tooling": "^1.2.101"
   },
   "peerDependencies": {
     "react-native-unistyles": ">=3.0.0"

package/src/builder.ts

@@ -30,7 +30,9 @@ import {
     TableSizeValue,
     TooltipSizeValue,
     ViewSizeValue,
+    FontScaleConfig,
 } from './theme/structures';
+import { applyFontScale, type ApplyFontScaleOptions } from './fontScale';
 
 /**
  * Mapping of component names to their size value types.
@@ -120,6 +122,14 @@ export type BuiltTheme<
     };
     interaction: InteractionConfig;
     breakpoints: Record<TBreakpoints, number>;
+    /** Font scale configuration. Undefined means no scaling (scale = 1.0). */
+    fontScaleConfig?: FontScaleConfig;
+    /**
+     * Unscaled base size values. Stored when fontScale != 1.0 so that
+     * runtime re-scaling can be done idempotently from the originals.
+     * @internal
+     */
+    __baseSizes?: Record<string, any>;
 };
 
 /**
@@ -135,7 +145,10 @@ type ThemeConfig<
     TBorder extends string,
     TSize extends string,
     TBreakpoints extends string,
-> = BuiltTheme<TIntents, TRadii, TShadows, TPallet, TSurface, TText, TBorder, TSize, TBreakpoints>;
+> = BuiltTheme<TIntents, TRadii, TShadows, TPallet, TSurface, TText, TBorder, TSize, TBreakpoints> & {
+    /** @internal Pending font scale to apply at build() time. Stored on config so it survives builder chaining. */
+    __pendingFontScale?: { scale: number; options?: ApplyFontScaleOptions };
+};
 
 /**
  * Fluent builder for creating themes with full TypeScript inference.
@@ -830,6 +843,54 @@ export class ThemeBuilder<
         return newBuilder;
     }
 
+    // =========================================================================
+    // Font Scale
+    // =========================================================================
+
+    /**
+     * Set a global font scale factor.
+     * When build() is called, all font-related size properties (fontSize, lineHeight,
+     * iconSize, etc.) will be multiplied by this factor.
+     *
+     * The unscaled base values are preserved on the built theme so that
+     * runtime re-scaling via applyFontScale() is idempotent.
+     *
+     * @param scale - The scale factor (1.0 = no change, 1.5 = 50% larger)
+     * @param options - Optional configuration
+     * @param options.scaleIcons - Whether to also scale iconSize properties (default: true)
+     * @param options.minScale - Minimum clamped scale (default: 0.5)
+     * @param options.maxScale - Maximum clamped scale (default: 3.0)
+     *
+     * @example
+     * ```typescript
+     * createTheme()
+     *   .setSizes({ ... })
+     *   .setFontScale(1.2)
+     *   .build();
+     * ```
+     *
+     * @example Using OS font scale at init
+     * ```typescript
+     * import { UnistylesRuntime } from 'react-native-unistyles';
+     *
+     * createTheme()
+     *   .setSizes({ ... })
+     *   .setFontScale(UnistylesRuntime.fontScale)
+     *   .build();
+     * ```
+     */
+    setFontScale(
+        scale: number,
+        options?: ApplyFontScaleOptions,
+    ): ThemeBuilder<TIntents, TRadii, TShadows, TPallet, TSurface, TText, TBorder, TSize, TBreakpoints> {
+        const newBuilder = new ThemeBuilder<TIntents, TRadii, TShadows, TPallet, TSurface, TText, TBorder, TSize, TBreakpoints>();
+        newBuilder.config = {
+            ...this.config,
+            __pendingFontScale: { scale, options },
+        };
+        return newBuilder;
+    }
+
     // =========================================================================
     // Build
     // =========================================================================
@@ -838,7 +899,11 @@ export class ThemeBuilder<
      * Build the final theme object.
      */
     build(): BuiltTheme<TIntents, TRadii, TShadows, TPallet, TSurface, TText, TBorder, TSize, TBreakpoints> {
-        return this.config;
+        const { __pendingFontScale, ...config } = this.config as any;
+        if (__pendingFontScale) {
+            return applyFontScale(config, __pendingFontScale.scale, __pendingFontScale.options);
+        }
+        return config;
     }
 }
 

package/src/fontScale.ts

@@ -0,0 +1,241 @@
+import type { BuiltTheme } from './builder';
+import type { FontScaleConfig, SizeValue, TypographyValue } from './theme/structures';
+
+// =============================================================================
+// Property Classification
+// =============================================================================
+
+/**
+ * Property names that represent font metrics and are always scaled.
+ */
+const FONT_PROPERTIES = new Set([
+    'fontSize',
+    'lineHeight',
+    'headerFontSize',
+    'labelFontSize',
+    'labelLineHeight',
+    'titleFontSize',
+    'titleLineHeight',
+    'messageFontSize',
+    'messageLineHeight',
+    'circularLabelFontSize',
+]);
+
+/**
+ * Property names that represent icon dimensions and are scaled when scaleIcons is true.
+ */
+const ICON_PROPERTIES = new Set([
+    'iconSize',
+    'thumbIconSize',
+    'closeIconSize',
+]);
+
+/**
+ * The 'icon' component's width/height represent icon glyph dimensions (not layout),
+ * so they are scaled when scaleIcons is true.
+ */
+const ICON_COMPONENT_KEY = 'icon';
+
+// =============================================================================
+// Scaling Helpers
+// =============================================================================
+
+function scaleSizeValue(value: SizeValue, scale: number): SizeValue {
+    if (typeof value === 'number') {
+        return Math.round(value * scale * 100) / 100;
+    }
+    return value;
+}
+
+function shouldScaleProperty(
+    key: string,
+    componentKey: string,
+    scaleIcons: boolean,
+): boolean {
+    if (FONT_PROPERTIES.has(key)) {
+        return true;
+    }
+    if (scaleIcons && ICON_PROPERTIES.has(key)) {
+        return true;
+    }
+    // Icon component's width/height are icon dimensions
+    if (scaleIcons && componentKey === ICON_COMPONENT_KEY && (key === 'width' || key === 'height')) {
+        return true;
+    }
+    return false;
+}
+
+function scaleSizeRecord(
+    record: Record<string, SizeValue>,
+    scale: number,
+    componentKey: string,
+    scaleIcons: boolean,
+): Record<string, SizeValue> {
+    const result: Record<string, SizeValue> = {};
+    for (const [key, value] of Object.entries(record)) {
+        result[key] = shouldScaleProperty(key, componentKey, scaleIcons)
+            ? scaleSizeValue(value, scale)
+            : value;
+    }
+    return result;
+}
+
+function scaleTypography(
+    typography: Record<string, TypographyValue>,
+    scale: number,
+): Record<string, TypographyValue> {
+    const result: Record<string, TypographyValue> = {};
+    for (const [key, value] of Object.entries(typography)) {
+        result[key] = {
+            fontSize: scaleSizeValue(value.fontSize, scale),
+            lineHeight: scaleSizeValue(value.lineHeight, scale),
+            fontWeight: value.fontWeight,
+        };
+    }
+    return result;
+}
+
+// =============================================================================
+// Public API
+// =============================================================================
+
+export type ApplyFontScaleOptions = {
+    /** Whether to scale icon sizes alongside fonts (default: true) */
+    scaleIcons?: boolean;
+    /** Minimum allowed scale factor (default: 0.5) */
+    minScale?: number;
+    /** Maximum allowed scale factor (default: 3.0) */
+    maxScale?: number;
+};
+
+/**
+ * Apply a font scale factor to a theme, returning a new theme with all
+ * font-related size properties scaled.
+ *
+ * Uses `__baseSizes` (if present) as the source for scaling, making this
+ * function idempotent — calling it multiple times with different scales
+ * always computes from the original unscaled values.
+ *
+ * @param theme - The theme to scale
+ * @param scale - The scale factor (1.0 = no change)
+ * @param options - Configuration
+ * @returns A new theme with scaled sizes, fontScaleConfig, and __baseSizes set
+ *
+ * @example
+ * ```typescript
+ * import { applyFontScale } from '@idealyst/theme';
+ *
+ * const scaledTheme = applyFontScale(lightTheme, 1.2);
+ * // scaledTheme.sizes.button.md.fontSize === 19.2 (was 16)
+ * ```
+ */
+export function applyFontScale<T extends BuiltTheme<any, any, any, any, any, any, any, any, any>>(
+    theme: T,
+    scale: number,
+    options?: ApplyFontScaleOptions,
+): T {
+    const scaleIcons = options?.scaleIcons ?? true;
+    const minScale = options?.minScale ?? 0.5;
+    const maxScale = options?.maxScale ?? 3.0;
+    const clampedScale = Math.min(maxScale, Math.max(minScale, scale));
+
+    // Use __baseSizes if available (idempotent rescaling), otherwise current sizes
+    const baseSizes = theme.__baseSizes ?? theme.sizes;
+
+    const fontScaleConfig: FontScaleConfig = {
+        fontScale: clampedScale,
+        scaleIcons,
+        minScale,
+        maxScale,
+    };
+
+    if (clampedScale === 1.0) {
+        return {
+            ...theme,
+            sizes: baseSizes,
+            fontScaleConfig,
+            __baseSizes: baseSizes,
+        };
+    }
+
+    // Scale each component's size records
+    const scaledSizes: Record<string, any> = {};
+    for (const [componentKey, sizeVariants] of Object.entries(baseSizes)) {
+        if (componentKey === 'typography') {
+            scaledSizes.typography = scaleTypography(
+                sizeVariants as Record<string, TypographyValue>,
+                clampedScale,
+            );
+        } else {
+            const scaledVariants: Record<string, any> = {};
+            for (const [variantKey, variantValue] of Object.entries(sizeVariants as Record<string, Record<string, SizeValue>>)) {
+                scaledVariants[variantKey] = scaleSizeRecord(
+                    variantValue,
+                    clampedScale,
+                    componentKey,
+                    scaleIcons,
+                );
+            }
+            scaledSizes[componentKey] = scaledVariants;
+        }
+    }
+
+    return {
+        ...theme,
+        sizes: scaledSizes as T['sizes'],
+        fontScaleConfig,
+        __baseSizes: baseSizes,
+    };
+}
+
+// =============================================================================
+// Content Size Category Mapping
+// =============================================================================
+
+/**
+ * Maps iOS/Android contentSizeCategory strings to numeric font scale factors.
+ *
+ * iOS values are based on Apple's Dynamic Type scale ratios for the default
+ * body text style. Android values use approximate equivalents.
+ *
+ * Returns 1.0 for unknown categories.
+ *
+ * @param category - The contentSizeCategory string from UnistylesRuntime
+ * @returns A numeric scale factor
+ *
+ * @example
+ * ```typescript
+ * import { contentSizeCategoryToScale } from '@idealyst/theme';
+ * import { UnistylesRuntime } from 'react-native-unistyles';
+ *
+ * const scale = contentSizeCategoryToScale(UnistylesRuntime.contentSizeCategory);
+ * ```
+ */
+export function contentSizeCategoryToScale(category: string): number {
+    const mapping: Record<string, number> = {
+        // iOS categories (runtime string values from IOSContentSizeCategory enum)
+        xSmall: 0.82,
+        Small: 0.88,
+        Medium: 0.94,
+        Large: 1.0, // iOS default
+        xLarge: 1.12,
+        xxLarge: 1.24,
+        xxxLarge: 1.35,
+        accessibilityMedium: 1.6,
+        accessibilityLarge: 1.9,
+        accessibilityExtraLarge: 2.35,
+        accessibilityExtraExtraLarge: 2.75,
+        accessibilityExtraExtraExtraLarge: 3.1,
+        // Android categories (runtime string values from AndroidContentSizeCategory enum)
+        Default: 1.0,
+        ExtraLarge: 1.24,
+        Huge: 1.35,
+        ExtraHuge: 1.6,
+        ExtraExtraHuge: 1.9,
+        // Web / unspecified
+        'web-unspecified': 1.0,
+        unspecified: 1.0,
+    };
+
+    return mapping[category] ?? 1.0;
+}

package/src/fontScaleRuntime.ts

@@ -0,0 +1,72 @@
+import { UnistylesRuntime } from 'react-native-unistyles';
+import { applyFontScale, type ApplyFontScaleOptions } from './fontScale';
+import type { FontScaleConfig } from './theme/structures';
+
+/**
+ * Options for updateFontScale.
+ */
+export type UpdateFontScaleOptions = ApplyFontScaleOptions & {
+    /** Theme names to update. Defaults to ['light', 'dark']. */
+    themes?: string[];
+};
+
+/**
+ * Update the font scale at runtime across registered Unistyles themes.
+ *
+ * Uses UnistylesRuntime.updateTheme() to recompute all font-related sizes,
+ * triggering automatic re-renders of all components that reference theme
+ * size values via stylesheets.
+ *
+ * @param scale - The new font scale factor (1.0 = no change)
+ * @param options - Configuration
+ *
+ * @example React to OS font size changes
+ * ```typescript
+ * import { updateFontScale, contentSizeCategoryToScale } from '@idealyst/theme';
+ * import { UnistylesRuntime } from 'react-native-unistyles';
+ *
+ * const osScale = contentSizeCategoryToScale(UnistylesRuntime.contentSizeCategory);
+ * updateFontScale(osScale);
+ * ```
+ *
+ * @example User preference from settings
+ * ```typescript
+ * function onFontScaleChange(newScale: number) {
+ *     updateFontScale(newScale);
+ * }
+ * ```
+ */
+export function updateFontScale(scale: number, options?: UpdateFontScaleOptions): void {
+    const { themes: themeNames = ['light', 'dark'], ...scaleOptions } = options ?? {};
+
+    for (const themeName of themeNames) {
+        try {
+            UnistylesRuntime.updateTheme(themeName as any, (currentTheme: any) => {
+                const existingConfig = currentTheme.fontScaleConfig as FontScaleConfig | undefined;
+                return applyFontScale(currentTheme, scale, {
+                    scaleIcons: scaleOptions.scaleIcons ?? existingConfig?.scaleIcons ?? true,
+                    minScale: scaleOptions.minScale ?? existingConfig?.minScale,
+                    maxScale: scaleOptions.maxScale ?? existingConfig?.maxScale,
+                });
+            });
+        } catch (error) {
+            // Theme may not be registered — silently skip
+            if (__DEV__) {
+                console.warn(`[idealyst/theme] Unable to update font scale for theme "${themeName}":`, error);
+            }
+        }
+    }
+}
+
+/**
+ * Get the current font scale from the active theme.
+ * Returns 1.0 if no font scale has been applied.
+ */
+export function getFontScale(): number {
+    try {
+        const theme = UnistylesRuntime.getTheme() as any;
+        return theme?.fontScaleConfig?.fontScale ?? 1.0;
+    } catch {
+        return 1.0;
+    }
+}

package/src/index.ts

@@ -28,6 +28,10 @@ export * from './useResponsiveStyle';
 // Color scheme utilities
 export * from './colorScheme';
 
+// Font scale utilities
+export { applyFontScale, contentSizeCategoryToScale, type ApplyFontScaleOptions } from './fontScale';
+export { updateFontScale, getFontScale, type UpdateFontScaleOptions } from './fontScaleRuntime';
+
 // Theme hook
 export { useTheme } from './useTheme';
 

package/src/theme/index.ts

@@ -49,4 +49,5 @@ export type {
     TableSizeValue,
     TooltipSizeValue,
     ViewSizeValue,
+    FontScaleConfig,
 } from "./structures";

package/src/theme/structures.ts

@@ -259,3 +259,18 @@ export type ViewSizeValue = {
     padding: SizeValue;
     spacing: SizeValue;
 };
+
+/**
+ * Font scale configuration stored on the built theme.
+ * Allows runtime utilities to recompute scaled values from base values.
+ */
+export type FontScaleConfig = {
+    /** The current font scale factor (1.0 = no scaling) */
+    fontScale: number;
+    /** Whether icon sizes should be scaled alongside fonts */
+    scaleIcons: boolean;
+    /** Minimum allowed scale factor */
+    minScale: number;
+    /** Maximum allowed scale factor */
+    maxScale: number;
+};