@idealyst/theme 1.1.6 → 1.1.8

package/src/extensions.ts

@@ -0,0 +1,110 @@
+/**
+ * Extensions runtime for Idealyst theme.
+ *
+ * This module provides the runtime helper used by the Babel plugin
+ * to merge extensions into component styles.
+ */
+
+export { __withExtension } from './babel/runtime';
+
+import { StyleSheet } from 'react-native-unistyles';
+import type { Theme } from './theme';
+
+// =============================================================================
+// ThemeStyleWrapper - Type utility for style definitions
+// =============================================================================
+
+// Check if T is an object we can iterate over (not array, not function, not primitive)
+type IsIterableObject<T> = T extends object
+  ? T extends any[]
+    ? false
+    : T extends (...args: any[]) => any
+      ? false
+      : true
+  : false;
+
+// Get value type from an object - works for both Record and named-key objects
+type ObjectValue<T> = T extends { [key: string]: infer V }
+  ? V
+  : T[keyof T];
+
+/**
+ * Wraps a Theme type to add $iterator properties for any object types.
+ *
+ * For each property that is an object (dictionary-like), adds a sibling $propertyName
+ * that represents the value type. This enables Babel to expand iterations
+ * over theme values (like intents, typography sizes, etc.)
+ *
+ * Works with:
+ * - Record<string, V> types
+ * - Objects with named keys like { primary: V, success: V, ... }
+ *
+ * @example
+ * ```typescript
+ * import { ThemeStyleWrapper } from '@idealyst/theme/extensions';
+ * import type { Theme as BaseTheme } from '@idealyst/theme';
+ *
+ * type Theme = ThemeStyleWrapper<BaseTheme>;
+ *
+ * // Now you can use $iterator properties:
+ * // theme.$intents.primary -> Babel expands to all intent keys
+ * // theme.sizes.$typography.fontSize -> Babel expands to all typography keys
+ * ```
+ */
+export type ThemeStyleWrapper<T> = T extends object
+  ? {
+      [K in keyof T]: ThemeStyleWrapper<T[K]>
+    } & {
+      [K in keyof T as IsIterableObject<T[K]> extends true ? `$${K & string}` : never]:
+        ThemeStyleWrapper<ObjectValue<T[K]>>
+    }
+  : T;
+
+/**
+ * Theme type with $iterator properties for use in style definitions.
+ * Use this instead of the base Theme type when using $iterator syntax.
+ */
+export type IteratorTheme = ThemeStyleWrapper<Theme>;
+
+/**
+ * Style callback type that accepts IteratorTheme.
+ * The variants structure is relaxed to accept $iterator patterns.
+ */
+export type IteratorStyleCallback<TStyles> = (theme: IteratorTheme) => TStyles;
+
+/**
+ * Creates a stylesheet with $iterator expansion support.
+ *
+ * This is a typed wrapper around StyleSheet.create that:
+ * 1. Accepts the IteratorTheme type (with $intents, $sizes, etc.)
+ * 2. Allows relaxed variant structures for $iterator patterns
+ *
+ * The Babel plugin will expand $iterator patterns before Unistyles processes the styles.
+ *
+ * @example
+ * ```typescript
+ * import { createIteratorStyles } from '@idealyst/theme';
+ *
+ * export const styles = createIteratorStyles((theme) => ({
+ *   box: {
+ *     borderRadius: theme.radii.md,
+ *     variants: {
+ *       intent: {
+ *         backgroundColor: theme.$intents.light,
+ *         borderColor: theme.$intents.primary,
+ *       },
+ *       size: {
+ *         padding: theme.sizes.$button.paddingVertical,
+ *       },
+ *     },
+ *   },
+ * }));
+ * ```
+ */
+export function createIteratorStyles<TStyles extends Record<string, any>>(
+  callback: IteratorStyleCallback<TStyles>
+): ReturnType<typeof StyleSheet.create> {
+  // This function is transformed by Babel - it sees StyleSheet.create and processes it
+  // The callback is passed through with $iterator patterns expanded
+  return StyleSheet.create(callback as any);
+}

package/src/helpers.ts

@@ -0,0 +1,206 @@
+import { IntentValue, Theme, Shade, ColorValue } from './theme';
+
+/**
+ * Deep partial type for nested objects.
+ */
+type DeepPartial<T> = {
+    [P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P];
+};
+
+/**
+ * Create an IntentValue with all required properties.
+ * Automatically generates light and dark variants if not provided.
+ *
+ * @param primary - The primary color for this intent
+ * @param contrast - The contrast color (typically for text on primary background)
+ * @param options - Optional overrides for light, dark, and any extended properties
+ * @returns A complete IntentValue object
+ *
+ * @example Basic usage
+ * ```typescript
+ * const brandIntent = createIntent('#8B5CF6', '#ffffff');
+ * ```
+ *
+ * @example With extended properties
+ * ```typescript
+ * const brandIntent = createIntent('#8B5CF6', '#ffffff', {
+ *   shadowColor: 'rgba(139, 92, 246, 0.3)',
+ *   hoverBackground: 'rgba(139, 92, 246, 0.1)',
+ * });
+ * ```
+ */
+export function createIntent(
+    primary: string,
+    contrast: string,
+    options?: Partial<Omit<IntentValue, 'primary' | 'contrast'>>
+): IntentValue {
+    return {
+        primary,
+        contrast,
+        light: options?.light ?? lightenColor(primary, 0.3),
+        dark: options?.dark ?? darkenColor(primary, 0.3),
+        ...options,
+    } as IntentValue;
+}
+
+/**
+ * Deep merge two objects together.
+ * The source object's values take priority over target.
+ *
+ * @param target - Base object
+ * @param source - Object to merge in (takes priority)
+ * @returns Merged object
+ */
+function deepMerge<T extends Record<string, any>>(target: T, source: DeepPartial<T>): T {
+    const result: Record<string, any> = { ...target };
+
+    for (const key in source) {
+        if (Object.prototype.hasOwnProperty.call(source, key)) {
+            const sourceValue = source[key];
+            const targetValue = result[key];
+
+            if (
+                sourceValue !== null &&
+                typeof sourceValue === 'object' &&
+                !Array.isArray(sourceValue) &&
+                targetValue !== null &&
+                typeof targetValue === 'object' &&
+                !Array.isArray(targetValue)
+            ) {
+                result[key] = deepMerge(targetValue, sourceValue as DeepPartial<typeof targetValue>);
+            } else if (sourceValue !== undefined) {
+                result[key] = sourceValue;
+            }
+        }
+    }
+
+    return result as T;
+}
+
+/**
+ * Extend a base theme with custom values.
+ * Performs a deep merge where extensions override base values.
+ *
+ * @param base - The base theme to extend (e.g., lightTheme or darkTheme)
+ * @param extensions - Partial theme object with values to override
+ * @returns Complete theme with extensions applied
+ *
+ * @example
+ * ```typescript
+ * import { lightTheme, extendTheme, createIntent } from '@idealyst/theme';
+ *
+ * const myTheme = extendTheme(lightTheme, {
+ *   intents: {
+ *     brand: createIntent('#8B5CF6', '#ffffff'),
+ *     accent: createIntent('#F59E0B', '#ffffff'),
+ *   },
+ *   colors: {
+ *     surface: {
+ *       elevated: '#ffffff',
+ *     },
+ *   },
+ * });
+ * ```
+ */
+export function extendTheme(base: Theme, extensions: DeepPartial<Theme>): Theme {
+    return deepMerge(base, extensions);
+}
+
+/**
+ * Generate a color palette (50-900 shades) from a base color.
+ * Uses the 500 shade as the base and interpolates lighter/darker variants.
+ *
+ * @param baseColor - The base color (hex format, e.g., '#8B5CF6')
+ * @returns Record of shade values (50-900)
+ *
+ * @example
+ * ```typescript
+ * const brandPalette = generatePalette('#8B5CF6');
+ * // brandPalette[50] = light variant
+ * // brandPalette[500] = base color
+ * // brandPalette[900] = dark variant
+ * ```
+ */
+export function generatePalette(baseColor: string): Record<Shade, ColorValue> {
+    const palette = {} as Record<Shade, ColorValue>;
+    const baseRgb = hexToRgb(baseColor);
+    const white: [number, number, number] = [255, 255, 255];
+    const black: [number, number, number] = [0, 0, 0];
+    const shades: Shade[] = [50, 100, 200, 300, 400, 500, 600, 700, 800, 900];
+
+    for (const shade of shades) {
+        if (shade === 500) {
+            palette[shade] = baseColor;
+        } else if (shade < 500) {
+            // Lighter shades - interpolate towards white
+            const factor = (500 - shade) / 450;
+            const interpolated = interpolateColor(baseRgb, white, factor);
+            palette[shade] = rgbToHex(...interpolated);
+        } else {
+            // Darker shades - interpolate towards black
+            const factor = (shade - 500) / 400;
+            const interpolated = interpolateColor(baseRgb, black, factor);
+            palette[shade] = rgbToHex(...interpolated);
+        }
+    }
+
+    return palette;
+}
+
+// ============================================================================
+// Internal Color Utilities
+// ============================================================================
+
+/**
+ * Convert hex color to RGB tuple.
+ */
+function hexToRgb(hex: string): [number, number, number] {
+    const cleanHex = hex.replace('#', '');
+    const r = parseInt(cleanHex.slice(0, 2), 16);
+    const g = parseInt(cleanHex.slice(2, 4), 16);
+    const b = parseInt(cleanHex.slice(4, 6), 16);
+    return [r, g, b];
+}
+
+/**
+ * Convert RGB tuple to hex color.
+ */
+function rgbToHex(r: number, g: number, b: number): string {
+    const toHex = (n: number) => Math.round(Math.max(0, Math.min(255, n))).toString(16).padStart(2, '0');
+    return `#${toHex(r)}${toHex(g)}${toHex(b)}`;
+}
+
+/**
+ * Interpolate between two RGB colors.
+ */
+function interpolateColor(
+    color1: [number, number, number],
+    color2: [number, number, number],
+    factor: number
+): [number, number, number] {
+    return [
+        color1[0] + (color2[0] - color1[0]) * factor,
+        color1[1] + (color2[1] - color1[1]) * factor,
+        color1[2] + (color2[2] - color1[2]) * factor,
+    ];
+}
+
+/**
+ * Lighten a color by a given factor.
+ */
+function lightenColor(hex: string, factor: number): string {
+    const rgb = hexToRgb(hex);
+    const white: [number, number, number] = [255, 255, 255];
+    const interpolated = interpolateColor(rgb, white, factor);
+    return rgbToHex(...interpolated);
+}
+
+/**
+ * Darken a color by a given factor.
+ */
+function darkenColor(hex: string, factor: number): string {
+    const rgb = hexToRgb(hex);
+    const black: [number, number, number] = [0, 0, 0];
+    const interpolated = interpolateColor(rgb, black, factor);
+    return rgbToHex(...interpolated);
+}

package/src/index.ts

@@ -1,7 +1,21 @@
-export * from './unistyles';
-export * from './lightTheme';
-export * from './darkTheme';
+// Core types first (no dependencies)
 export * from './theme';
 export * from './variants';
 export * from './components';
-export * from './styles';
+
+// Builder (depends on theme types)
+export * from './builder';
+
+// Themes (depend on builder)
+export * from './lightTheme';
+export * from './darkTheme';
+
+// Unistyles declaration (depends on theme)
+export * from './unistyles';
+
+// Helpers and styles
+export * from './styles';
+export * from './helpers';
+export * from './styleBuilder';
+export * from './extensions';
+export * from './componentStyles';