@idealyst/theme 1.1.7 → 1.1.9

package/src/breakpoints.ts

@@ -0,0 +1,112 @@
+import { UnistylesRuntime } from 'react-native-unistyles';
+import { Breakpoint, BreakpointsRecord } from './theme/breakpoint';
+
+/**
+ * Get the current active breakpoint name.
+ *
+ * @returns The current breakpoint name, or undefined if not available
+ *
+ * @example
+ * ```typescript
+ * const current = getCurrentBreakpoint();
+ * console.log(current); // 'md'
+ * ```
+ */
+export function getCurrentBreakpoint(): Breakpoint | undefined {
+    return UnistylesRuntime.breakpoint as Breakpoint | undefined;
+}
+
+/**
+ * Get all registered breakpoints and their values.
+ *
+ * @returns Object mapping breakpoint names to pixel values
+ *
+ * @example
+ * ```typescript
+ * const breakpoints = getBreakpoints();
+ * console.log(breakpoints); // { xs: 0, sm: 576, md: 768, lg: 992, xl: 1200 }
+ * ```
+ */
+export function getBreakpoints(): BreakpointsRecord {
+    return UnistylesRuntime.breakpoints as BreakpointsRecord;
+}
+
+/**
+ * Check if the current viewport is at or above a specific breakpoint.
+ *
+ * @param breakpoint - The breakpoint to check against
+ * @returns True if the current viewport width is >= the breakpoint value
+ *
+ * @example
+ * ```typescript
+ * if (isBreakpointUp('md')) {
+ *   // Tablet or larger
+ * }
+ * ```
+ */
+export function isBreakpointUp(breakpoint: Breakpoint): boolean {
+    const breakpoints = getBreakpoints();
+    const screenWidth = UnistylesRuntime.screen.width;
+    return screenWidth >= breakpoints[breakpoint];
+}
+
+/**
+ * Check if the current viewport is below a specific breakpoint.
+ *
+ * @param breakpoint - The breakpoint to check against
+ * @returns True if the current viewport width is < the breakpoint value
+ *
+ * @example
+ * ```typescript
+ * if (isBreakpointDown('md')) {
+ *   // Mobile only (below tablet)
+ * }
+ * ```
+ */
+export function isBreakpointDown(breakpoint: Breakpoint): boolean {
+    return !isBreakpointUp(breakpoint);
+}
+
+/**
+ * Resolve a responsive value to its current breakpoint value.
+ * Falls back to the smallest defined breakpoint using CSS cascade behavior.
+ *
+ * @param value - Either a direct value or an object mapping breakpoints to values
+ * @returns The resolved value for the current breakpoint
+ *
+ * @example
+ * ```typescript
+ * // On a tablet (md breakpoint):
+ * const size = resolveResponsive({ xs: 'sm', md: 'lg' });
+ * console.log(size); // 'lg'
+ *
+ * // On a phone (xs breakpoint):
+ * const size = resolveResponsive({ xs: 'sm', md: 'lg' });
+ * console.log(size); // 'sm'
+ * ```
+ */
+export function resolveResponsive<T>(value: T | Partial<Record<Breakpoint, T>>): T | undefined {
+    // If not an object, return directly
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        return value as T;
+    }
+
+    const responsiveValue = value as Partial<Record<Breakpoint, T>>;
+    const breakpoints = getBreakpoints();
+    const screenWidth = UnistylesRuntime.screen.width;
+
+    // Sort breakpoints by value descending
+    const sortedBps = Object.entries(breakpoints)
+        .sort(([, a], [, b]) => b - a)
+        .map(([name]) => name as Breakpoint);
+
+    // Find the largest breakpoint that matches current screen width
+    // and has a defined value (CSS cascade behavior)
+    for (const bp of sortedBps) {
+        if (screenWidth >= breakpoints[bp] && responsiveValue[bp] !== undefined) {
+            return responsiveValue[bp];
+        }
+    }
+
+    return undefined;
+}

package/src/builder.ts

@@ -42,6 +42,7 @@ export type BuiltTheme<
     TText extends string,
     TBorder extends string,
     TSize extends string,
+    TBreakpoints extends string = never,
 > = {
     intents: Record<TIntents, IntentValue>;
     radii: Record<TRadii, number>;
@@ -78,6 +79,7 @@ export type BuiltTheme<
         typography: Record<Typography, TypographyValue>;
     };
     interaction: InteractionConfig;
+    breakpoints: Record<TBreakpoints, number>;
 };
 
 /**
@@ -92,7 +94,8 @@ type ThemeConfig<
     TText extends string,
     TBorder extends string,
     TSize extends string,
-> = BuiltTheme<TIntents, TRadii, TShadows, TPallet, TSurface, TText, TBorder, TSize>;
+    TBreakpoints extends string,
+> = BuiltTheme<TIntents, TRadii, TShadows, TPallet, TSurface, TText, TBorder, TSize, TBreakpoints>;
 
 /**
  * Fluent builder for creating themes with full TypeScript inference.
@@ -127,8 +130,9 @@ export class ThemeBuilder<
     TText extends string = never,
     TBorder extends string = never,
     TSize extends string = never,
+    TBreakpoints extends string = never,
 > {
-    private config: ThemeConfig<TIntents, TRadii, TShadows, TPallet, TSurface, TText, TBorder, TSize>;
+    private config: ThemeConfig<TIntents, TRadii, TShadows, TPallet, TSurface, TText, TBorder, TSize, TBreakpoints>;
 
     constructor() {
         this.config = {
@@ -143,6 +147,7 @@ export class ThemeBuilder<
             },
             sizes: {} as any,
             interaction: {} as any,
+            breakpoints: {} as any,
         };
     }
 
@@ -152,8 +157,8 @@ export class ThemeBuilder<
     addIntent<K extends string>(
         name: K,
         value: IntentValue
-    ): ThemeBuilder<TIntents | K, TRadii, TShadows, TPallet, TSurface, TText, TBorder, TSize> {
-        const newBuilder = new ThemeBuilder<TIntents | K, TRadii, TShadows, TPallet, TSurface, TText, TBorder, TSize>();
+    ): ThemeBuilder<TIntents | K, TRadii, TShadows, TPallet, TSurface, TText, TBorder, TSize, TBreakpoints> {
+        const newBuilder = new ThemeBuilder<TIntents | K, TRadii, TShadows, TPallet, TSurface, TText, TBorder, TSize, TBreakpoints>();
         newBuilder.config = {
             ...this.config,
             intents: {
@@ -170,8 +175,8 @@ export class ThemeBuilder<
     addRadius<K extends string>(
         name: K,
         value: number
-    ): ThemeBuilder<TIntents, TRadii | K, TShadows, TPallet, TSurface, TText, TBorder, TSize> {
-        const newBuilder = new ThemeBuilder<TIntents, TRadii | K, TShadows, TPallet, TSurface, TText, TBorder, TSize>();
+    ): ThemeBuilder<TIntents, TRadii | K, TShadows, TPallet, TSurface, TText, TBorder, TSize, TBreakpoints> {
+        const newBuilder = new ThemeBuilder<TIntents, TRadii | K, TShadows, TPallet, TSurface, TText, TBorder, TSize, TBreakpoints>();
         newBuilder.config = {
             ...this.config,
             radii: {
@@ -188,8 +193,8 @@ export class ThemeBuilder<
     addShadow<K extends string>(
         name: K,
         value: ShadowValue
-    ): ThemeBuilder<TIntents, TRadii, TShadows | K, TPallet, TSurface, TText, TBorder, TSize> {
-        const newBuilder = new ThemeBuilder<TIntents, TRadii, TShadows | K, TPallet, TSurface, TText, TBorder, TSize>();
+    ): ThemeBuilder<TIntents, TRadii, TShadows | K, TPallet, TSurface, TText, TBorder, TSize, TBreakpoints> {
+        const newBuilder = new ThemeBuilder<TIntents, TRadii, TShadows | K, TPallet, TSurface, TText, TBorder, TSize, TBreakpoints>();
         newBuilder.config = {
             ...this.config,
             shadows: {
@@ -205,8 +210,8 @@ export class ThemeBuilder<
      */
     setInteraction(
         interaction: InteractionConfig
-    ): ThemeBuilder<TIntents, TRadii, TShadows, TPallet, TSurface, TText, TBorder, TSize> {
-        const newBuilder = new ThemeBuilder<TIntents, TRadii, TShadows, TPallet, TSurface, TText, TBorder, TSize>();
+    ): 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,
             interaction,
@@ -227,8 +232,8 @@ export class ThemeBuilder<
         surface: Record<S, ColorValue>;
         text: Record<T, ColorValue>;
         border: Record<B, ColorValue>;
-    }): ThemeBuilder<TIntents, TRadii, TShadows, P, S, T, B, TSize> {
-        const newBuilder = new ThemeBuilder<TIntents, TRadii, TShadows, P, S, T, B, TSize>();
+    }): ThemeBuilder<TIntents, TRadii, TShadows, P, S, T, B, TSize, TBreakpoints> {
+        const newBuilder = new ThemeBuilder<TIntents, TRadii, TShadows, P, S, T, B, TSize, TBreakpoints>();
         newBuilder.config = {
             ...this.config,
             colors,
@@ -263,8 +268,8 @@ export class ThemeBuilder<
         tooltip: Record<S, TooltipSizeValue>;
         view: Record<S, ViewSizeValue>;
         typography: Record<Typography, TypographyValue>;
-    }): ThemeBuilder<TIntents, TRadii, TShadows, TPallet, TSurface, TText, TBorder, S> {
-        const newBuilder = new ThemeBuilder<TIntents, TRadii, TShadows, TPallet, TSurface, TText, TBorder, S>();
+    }): ThemeBuilder<TIntents, TRadii, TShadows, TPallet, TSurface, TText, TBorder, S, TBreakpoints> {
+        const newBuilder = new ThemeBuilder<TIntents, TRadii, TShadows, TPallet, TSurface, TText, TBorder, S, TBreakpoints>();
         newBuilder.config = {
             ...this.config,
             sizes,
@@ -272,10 +277,75 @@ export class ThemeBuilder<
         return newBuilder;
     }
 
+    /**
+     * Add a single breakpoint to the theme.
+     *
+     * IMPORTANT: At least one breakpoint must have value 0 (typically 'xs').
+     * This simulates CSS cascading behavior in Unistyles.
+     *
+     * @param name - The breakpoint name (e.g., 'xs', 'sm', 'md')
+     * @param value - The minimum width in pixels for this breakpoint
+     *
+     * @example
+     * ```typescript
+     * createTheme()
+     *   .addBreakpoint('xs', 0)
+     *   .addBreakpoint('sm', 576)
+     *   .addBreakpoint('md', 768)
+     *   .build();
+     * ```
+     */
+    addBreakpoint<K extends string>(
+        name: K,
+        value: number
+    ): ThemeBuilder<TIntents, TRadii, TShadows, TPallet, TSurface, TText, TBorder, TSize, TBreakpoints | K> {
+        const newBuilder = new ThemeBuilder<TIntents, TRadii, TShadows, TPallet, TSurface, TText, TBorder, TSize, TBreakpoints | K>();
+        newBuilder.config = {
+            ...this.config,
+            breakpoints: {
+                ...this.config.breakpoints,
+                [name]: value,
+            } as any,
+        };
+        return newBuilder;
+    }
+
+    /**
+     * Set all breakpoints at once.
+     *
+     * IMPORTANT: At least one breakpoint must have value 0.
+     * Breakpoints define responsive behavior based on viewport width.
+     *
+     * @param breakpoints - Object mapping breakpoint names to pixel values
+     *
+     * @example
+     * ```typescript
+     * createTheme()
+     *   .setBreakpoints({
+     *     xs: 0,    // Required: starts at 0
+     *     sm: 576,
+     *     md: 768,
+     *     lg: 992,
+     *     xl: 1200,
+     *   })
+     *   .build();
+     * ```
+     */
+    setBreakpoints<B extends Record<string, number>>(
+        breakpoints: B
+    ): ThemeBuilder<TIntents, TRadii, TShadows, TPallet, TSurface, TText, TBorder, TSize, keyof B & string> {
+        const newBuilder = new ThemeBuilder<TIntents, TRadii, TShadows, TPallet, TSurface, TText, TBorder, TSize, keyof B & string>();
+        newBuilder.config = {
+            ...this.config,
+            breakpoints,
+        } as any;
+        return newBuilder;
+    }
+
     /**
      * Build the final theme object.
      */
-    build(): BuiltTheme<TIntents, TRadii, TShadows, TPallet, TSurface, TText, TBorder, TSize> {
+    build(): BuiltTheme<TIntents, TRadii, TShadows, TPallet, TSurface, TText, TBorder, TSize, TBreakpoints> {
         return this.config;
     }
 }
@@ -290,7 +360,7 @@ export function createTheme(): ThemeBuilder {
 /**
  * Create a builder from an existing theme to add more values.
  */
-export function fromTheme<T extends BuiltTheme<any, any, any, any, any, any, any, any>>(
+export function fromTheme<T extends BuiltTheme<any, any, any, any, any, any, any, any, any>>(
     base: T
 ): ThemeBuilder<
     keyof T['intents'] & string,
@@ -300,7 +370,8 @@ export function fromTheme<T extends BuiltTheme<any, any, any, any, any, any, any
     keyof T['colors']['surface'] & string,
     keyof T['colors']['text'] & string,
     keyof T['colors']['border'] & string,
-    keyof T['sizes']['button'] & string
+    keyof T['sizes']['button'] & string,
+    keyof T['breakpoints'] & string
 > {
     const builder = new ThemeBuilder<
         keyof T['intents'] & string,
@@ -310,7 +381,8 @@ export function fromTheme<T extends BuiltTheme<any, any, any, any, any, any, any
         keyof T['colors']['surface'] & string,
         keyof T['colors']['text'] & string,
         keyof T['colors']['border'] & string,
-        keyof T['sizes']['button'] & string
+        keyof T['sizes']['button'] & string,
+        keyof T['breakpoints'] & string
     >();
     (builder as any).config = { ...base };
     return builder;

package/src/componentStyles.ts

@@ -0,0 +1,93 @@
+/**
+ * Component Style Types Registry
+ *
+ * This module provides type definitions for component styles used with
+ * defineStyle, extendStyle, and overrideStyle.
+ *
+ * Components register their style types via module augmentation:
+ *
+ * @example
+ * ```typescript
+ * // In Text.styles.tsx
+ * declare module '@idealyst/theme' {
+ *   interface ComponentStyleRegistry {
+ *     Text: TextStyleDef;
+ *   }
+ * }
+ * ```
+ */
+
+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.
+ */
+export interface ComponentStyleRegistry {
+  // Components augment this interface to add their style types
+  // Example: Text: { text: (params: TextStyleParams) => TextStyleObject }
+}
+
+/**
+ * Get the style definition type for a component.
+ * Returns the registered type or a loose Record type for unregistered components.
+ */
+export type ComponentStyleDef<K extends string> = K extends keyof ComponentStyleRegistry
+  ? ComponentStyleRegistry[K]
+  : Record<string, any>;
+
+/**
+ * Deep partial type that works with functions.
+ * For style functions, preserves the function signature but makes the return type partial.
+ */
+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;
+
+/**
+ * Style definition for extendStyle - requires functions with same params as base.
+ * All style properties must be functions to access dynamic params.
+ */
+export type ExtendStyleDef<K extends string> = DeepPartialStyle<ComponentStyleDef<K>>;
+
+/**
+ * Style definition for overrideStyle - requires full implementation with functions.
+ */
+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
+// =============================================================================
+
+/**
+ * Base style object with optional variants and compound variants.
+ */
+export interface StyleWithVariants<TVariants extends Record<string, any> = Record<string, any>> {
+  variants?: {
+    [K in keyof TVariants]?: {
+      [V in TVariants[K] extends string | boolean ? TVariants[K] : string]?: ViewStyle | TextStyle;
+    };
+  };
+  compoundVariants?: Array<{
+    [K in keyof TVariants]?: TVariants[K];
+  } & { styles: ViewStyle | TextStyle }>;
+}
+
+/**
+ * Dynamic style function type.
+ */
+export type DynamicStyleFn<TParams, TStyle> = (params: TParams) => TStyle;

package/src/config/cli.ts

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+/**
+ * Idealyst Style Generator CLI
+ *
+ * Reads idealyst.config.ts and generates flat Unistyles-compatible style files.
+ *
+ * Usage:
+ *   npx ts-node packages/theme/src/config/cli.ts [config-path] [output-dir]
+ *
+ * Defaults:
+ *   config-path: ./idealyst.config.ts
+ *   output-dir:  ./generated
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+
+// Dynamic import for ESM compatibility
+async function main() {
+    const args = process.argv.slice(2);
+    const configPath = args[0] || './idealyst.config.ts';
+    const outputDir = args[1] || './generated';
+
+    console.log('🎨 Idealyst Style Generator');
+    console.log(`   Config: ${configPath}`);
+    console.log(`   Output: ${outputDir}`);
+    console.log('');
+
+    // Resolve paths
+    const resolvedConfigPath = path.resolve(process.cwd(), configPath);
+    const resolvedOutputDir = path.resolve(process.cwd(), outputDir);
+
+    // Check config exists
+    if (!fs.existsSync(resolvedConfigPath)) {
+        console.error(`❌ Config file not found: ${resolvedConfigPath}`);
+        console.error('');
+        console.error('Create an idealyst.config.ts file with your theme configuration.');
+        console.error('See the documentation for examples.');
+        process.exit(1);
+    }
+
+    // Import config dynamically
+    // Note: This requires ts-node or a pre-compiled config
+    let config;
+    try {
+        // Try to import the config
+        const configModule = await import(resolvedConfigPath);
+        config = configModule.default || configModule;
+    } catch (err) {
+        console.error(`❌ Failed to load config: ${err}`);
+        console.error('');
+        console.error('Make sure your config file:');
+        console.error('  1. Is a valid TypeScript/JavaScript file');
+        console.error('  2. Uses export default or named exports');
+        console.error('  3. Has all required theme properties');
+        process.exit(1);
+    }
+
+    // Validate config
+    if (!config.themes || !config.themes.light || !config.themes.dark) {
+        console.error('❌ Invalid config: themes.light and themes.dark are required');
+        process.exit(1);
+    }
+
+    // Import generator
+    const { generateStyles } = await import('./generator');
+
+    // Generate styles
+    console.log('⚙️  Generating styles...');
+    const files = generateStyles(config);
+
+    // Ensure output directory exists
+    if (!fs.existsSync(resolvedOutputDir)) {
+        fs.mkdirSync(resolvedOutputDir, { recursive: true });
+    }
+
+    // Write files
+    for (const [filename, content] of Object.entries(files)) {
+        const filePath = path.join(resolvedOutputDir, filename);
+        fs.writeFileSync(filePath, content, 'utf-8');
+        console.log(`   ✓ ${filename}`);
+    }
+
+    console.log('');
+    console.log(`✅ Generated ${Object.keys(files).length} files in ${outputDir}`);
+    console.log('');
+    console.log('Next steps:');
+    console.log('  1. Import the generated unistyles.generated.ts in your app entry');
+    console.log('  2. Update components to import from generated style files');
+}
+
+main().catch((err) => {
+    console.error('Fatal error:', err);
+    process.exit(1);
+});