@tachui/core 0.7.0-alpha1

package/src/assets/FontAsset.ts

@@ -0,0 +1,380 @@
+/**
+ * FontAsset - Font management for TachUI Asset system
+ *
+ * Provides SwiftUI-style font handling with web font loading capabilities
+ */
+
+import { Asset } from './Asset'
+
+export interface FontAssetOptions {
+  /** URL to the font file or CSS containing @font-face */
+  fontUrl?: string
+  /** Font format hint for older browsers */
+  fontFormat?: 'woff2' | 'woff' | 'truetype' | 'opentype' | 'embedded-opentype'
+  /** Loading strategy */
+  loading?: 'eager' | 'lazy'
+  /** Font weight range for variable fonts */
+  weightRange?: [number, number]
+  /** Font width range for variable fonts */
+  widthRange?: [number, number]
+  /** Variable font axes */
+  variableAxes?: Record<string, [number, number]>
+  /** Font display CSS property */
+  fontDisplay?: 'auto' | 'block' | 'swap' | 'fallback' | 'optional'
+  /** Preconnect to font host for performance */
+  preconnect?: boolean
+}
+
+export class FontAsset extends Asset {
+  public readonly family: string
+  public readonly fallbacks: string[]
+  public readonly options: FontAssetOptions
+  private loaded = false
+  private loadPromise: Promise<void> | null = null
+
+  constructor(
+    family: string,
+    fallbacks: string[] = [],
+    name: string = '',
+    options: FontAssetOptions = {}
+  ) {
+    super(name || family)
+    this.family = family
+    this.fallbacks = fallbacks
+    this.options = {
+      loading: 'lazy',
+      fontDisplay: 'swap',
+      preconnect: true,
+      ...options
+    }
+
+    // Eager load if specified
+    if (this.options.loading === 'eager') {
+      this.load()
+    }
+  }
+
+  /**
+   * Static factory method for SwiftUI-style initialization
+   */
+  static init(
+    family: string,
+    fallbacks: string[] = [],
+    name?: string,
+    options: FontAssetOptions = {}
+  ): FontAsset {
+    return new FontAsset(family, fallbacks, name, options)
+  }
+
+  /**
+   * Get the full font-family CSS value including fallbacks
+   */
+  get value(): string {
+    const families = [this.family, ...this.fallbacks]
+    return families
+      .map(f => f.includes(' ') ? `"${f}"` : f)
+      .join(', ')
+  }
+
+  /**
+   * Load the font if not already loaded
+   */
+  async load(): Promise<void> {
+    if (this.loaded || !this.options.fontUrl) {
+      return
+    }
+
+    if (this.loadPromise) {
+      return this.loadPromise
+    }
+
+    this.loadPromise = this.loadFont()
+    await this.loadPromise
+    this.loaded = true
+  }
+
+  /**
+   * Internal font loading implementation
+   */
+  private async loadFont(): Promise<void> {
+    const { fontUrl, preconnect } = this.options
+
+    if (!fontUrl) {
+      return
+    }
+
+    // Add preconnect hint if enabled
+    if (preconnect && typeof document !== 'undefined' && document.querySelector) {
+      try {
+        const url = new URL(fontUrl)
+        const origin = url.origin
+
+        if (!document.querySelector(`link[rel="preconnect"][href="${origin}"]`)) {
+          const link = document.createElement('link')
+          link.rel = 'preconnect'
+          link.href = origin
+          link.crossOrigin = 'anonymous'
+          document.head.appendChild(link)
+        }
+      } catch (_error) {
+        // Invalid URL, skip preconnect
+      }
+    }
+
+    // Load font based on URL type
+    if (fontUrl.endsWith('.css') || fontUrl.includes('fonts.googleapis.com')) {
+      // Load CSS file containing @font-face
+      await this.loadFontCSS(fontUrl)
+    } else {
+      // Load font file directly
+      await this.loadFontFile(fontUrl)
+    }
+
+    // Use Font Loading API if available
+    if ('fonts' in document) {
+      try {
+        await document.fonts.ready
+
+        // Check if our font loaded using proper CSS font shorthand syntax
+        // Quote font family names that contain spaces
+        const quotedFamily = this.family.includes(' ') ? `"${this.family}"` : this.family
+        const fontShorthand = `16px ${quotedFamily}`
+
+        const loaded = document.fonts.check(fontShorthand)
+        if (!loaded) {
+          console.warn(`⚠️ Font "${this.family}" may not have loaded correctly`)
+        }
+      } catch (_error) {
+        // This is just a validation check - font might still work fine
+      }
+    }
+  }
+
+  /**
+   * Load a CSS file containing @font-face rules
+   */
+  private async loadFontCSS(url: string): Promise<void> {
+    return new Promise((resolve, _reject) => {
+      // Check if link already exists to avoid duplicates
+      const existingLink = document.querySelector(`link[href="${url}"]`)
+      if (existingLink) {
+        resolve()
+        return
+      }
+
+      const link = document.createElement('link')
+      link.rel = 'stylesheet'
+      link.href = url
+      // Don't set crossOrigin for Google Fonts as it doesn't support CORS
+
+      link.onload = () => {
+        resolve()
+      }
+
+      link.onerror = (_error) => {
+        console.warn(`⚠️ Failed to load font CSS for ${this.family}:`, url)
+        // Don't reject - just resolve to allow fallback fonts
+        resolve()
+      }
+
+      document.head.appendChild(link)
+    })
+  }
+
+  /**
+   * Load a font file directly and create @font-face rule
+   */
+  private async loadFontFile(url: string): Promise<void> {
+    const { fontFormat, fontDisplay, weightRange, widthRange } = this.options
+
+    // Determine format string
+    let format = ''
+    if (fontFormat) {
+      format = `format('${fontFormat}')`
+    } else if (url.endsWith('.woff2')) {
+      format = "format('woff2')"
+    } else if (url.endsWith('.woff')) {
+      format = "format('woff')"
+    } else if (url.endsWith('.ttf')) {
+      format = "format('truetype')"
+    }
+
+    // Build @font-face rule
+    let fontFace = `
+      @font-face {
+        font-family: "${this.family}";
+        src: url("${url}") ${format};
+        font-display: ${fontDisplay || 'swap'};
+    `
+
+    // Add variable font descriptors
+    if (weightRange) {
+      fontFace += `font-weight: ${weightRange[0]} ${weightRange[1]};\n`
+    }
+    if (widthRange) {
+      fontFace += `font-stretch: ${widthRange[0]}% ${widthRange[1]}%;\n`
+    }
+
+    fontFace += '}'
+
+    // Add CSS to document
+    const style = document.createElement('style')
+    style.textContent = fontFace
+    document.head.appendChild(style)
+
+    // Use FontFace API if available for better loading control
+    if ('FontFace' in window) {
+      try {
+        const fontFaceObj = new FontFace(this.family, `url(${url})`, {
+          display: fontDisplay || 'swap',
+          weight: weightRange ? `${weightRange[0]} ${weightRange[1]}` : undefined,
+          stretch: widthRange ? `${widthRange[0]}% ${widthRange[1]}%` : undefined,
+        })
+
+        await fontFaceObj.load()
+        document.fonts.add(fontFaceObj)
+      } catch (_error) {
+        // FontFace API loading failed, font fallback will be used
+      }
+    }
+  }
+
+  /**
+   * Create a CSS variable for this font
+   */
+  toCSSVariable(varName?: string): string {
+    const cssVarName = varName || `--font-${this.name.toLowerCase().replace(/\s+/g, '-')}`
+    return `${cssVarName}: ${this.value};`
+  }
+
+  /**
+   * Get debug information
+   */
+  [Symbol.for('nodejs.util.inspect.custom')](): string {
+    return `FontAsset(${this.family}, loaded: ${this.loaded})`
+  }
+
+  /**
+   * Resolve the font value (required by Asset base class)
+   */
+  resolve(): string {
+    // Trigger lazy loading if configured
+    if (this.options.loading === 'lazy' && !this.loaded && this.options.fontUrl) {
+      this.load()
+    }
+    return this.value
+  }
+}
+
+// Font weight constants matching SwiftUI
+export const FontWeightPreset = {
+  ultraLight: 100,
+  thin: 200,
+  light: 300,
+  regular: 400,
+  medium: 500,
+  semibold: 600,
+  bold: 700,
+  heavy: 800,
+  black: 900,
+} as const
+
+export type FontWeightValue = typeof FontWeightPreset[keyof typeof FontWeightPreset]
+
+// Font width constants for variable fonts
+export const FontWidth = {
+  ultraCondensed: 50,
+  extraCondensed: 62.5,
+  condensed: 75,
+  semiCondensed: 87.5,
+  normal: 100,
+  semiExpanded: 112.5,
+  expanded: 125,
+  extraExpanded: 150,
+  ultraExpanded: 200,
+} as const
+
+export type FontWidthValue = typeof FontWidth[keyof typeof FontWidth]
+
+// Common system font stacks
+export const SystemFonts = {
+  sansSerif: ['system-ui', '-apple-system', 'BlinkMacSystemFont', 'Segoe UI', 'Roboto', 'Helvetica Neue', 'Arial', 'sans-serif'],
+  serif: ['Georgia', 'Cambria', 'Times New Roman', 'Times', 'serif'],
+  monospace: ['ui-monospace', 'SFMono-Regular', 'SF Mono', 'Consolas', 'Liberation Mono', 'Menlo', 'Courier', 'monospace'],
+  cursive: ['cursive'],
+  fantasy: ['fantasy'],
+} as const
+
+// Convenience factory functions
+export function createSystemFont(
+  type: keyof typeof SystemFonts = 'sansSerif',
+  name?: string
+): FontAsset {
+  return new FontAsset('', [...SystemFonts[type]], name || `system-${type}`)
+}
+
+/**
+ * Create a FontAsset that loads a Google Font
+ *
+ * @param family - Font family name (e.g., 'Inter', 'Source Sans 3')
+ * @param weights - Array of font weights to load (e.g., [300, 400, 700])
+ * @param name - Optional asset name (defaults to family name)
+ * @param options - Additional font options
+ * @returns FontAsset configured for Google Fonts
+ */
+export function createGoogleFont(
+  family: string,
+  weights: number[] = [400],
+  name?: string,
+  options: Omit<FontAssetOptions, 'fontUrl'> = {}
+): FontAsset {
+  // Generate Google Fonts CSS API v2 URL
+  // Note: API v2 uses semicolons instead of commas for multiple weights
+  const weightsParam = weights.join(';')
+
+  // Handle URL encoding properly - replace spaces with + for Google Fonts
+  const encodedFamily = family.replace(/\s+/g, '+')
+
+  // Build the CSS API URL
+  const fontUrl = `https://fonts.googleapis.com/css2?family=${encodedFamily}:wght@${weightsParam}&display=swap`
+  // console.log(`🔗 Generated Google Fonts URL for "${family}": ${fontUrl}`)
+
+  return new FontAsset(
+    family,
+    [...SystemFonts.sansSerif],
+    name || family.toLowerCase().replace(/\s+/g, '-'),
+    {
+      ...options,
+      fontUrl,
+      preconnect: true,
+    }
+  )
+}
+
+export function createVariableFont(
+  family: string,
+  fontUrl: string,
+  axes: {
+    weight?: [number, number]
+    width?: [number, number]
+    slant?: [number, number]
+    optical?: [number, number]
+    custom?: Record<string, [number, number]>
+  },
+  fallbacks: string[] = [...SystemFonts.sansSerif],
+  name?: string
+): FontAsset {
+  const variableAxes: Record<string, [number, number]> = {}
+
+  if (axes.slant) variableAxes.slnt = axes.slant
+  if (axes.optical) variableAxes.opsz = axes.optical
+  if (axes.custom) Object.assign(variableAxes, axes.custom)
+
+  return new FontAsset(family, fallbacks, name, {
+    fontUrl,
+    weightRange: axes.weight,
+    widthRange: axes.width,
+    variableAxes,
+    fontDisplay: 'swap',
+  })
+}

package/src/assets/ImageAsset.ts

@@ -0,0 +1,91 @@
+/**
+ * Image Asset for TachUI Assets system
+ *
+ * Represents a theme-adaptive image with light and dark variants.
+ */
+
+import { getCurrentTheme as _getCurrentTheme, getThemeSignal } from '../reactive/theme'
+import { getCurrentComputation } from '../reactive/context'
+import { Asset } from './Asset'
+
+/**
+ * ImageAsset initialization options
+ */
+export interface ImageAssetOptions {
+  default: string  // Required - fallback for any theme
+  light?: string   // Optional - light theme override
+  dark?: string    // Optional - dark theme override  
+  name: string     // Required - asset identifier
+  options?: { alt?: string; placeholder?: string } // Optional - metadata
+}
+
+export class ImageAsset extends Asset {
+  public readonly default: string
+  public readonly light?: string
+  public readonly dark?: string
+  public readonly alt?: string
+  public readonly placeholder?: string
+
+  constructor(options: ImageAssetOptions) {
+    super(options.name)
+
+    // Validate that default is provided
+    if (!options.default) {
+      throw new Error(`ImageAsset "${options.name}" must specify a default image path`)
+    }
+
+    this.default = options.default
+    this.light = options.light
+    this.dark = options.dark
+    this.alt = options.options?.alt
+    this.placeholder = options.options?.placeholder
+  }
+
+  static init(options: ImageAssetOptions): ImageAsset {
+    return new ImageAsset(options)
+  }
+
+  static getCurrentTheme(): string {
+    return _getCurrentTheme()
+  }
+
+  resolve(): string {
+    // If we're inside a reactive computation (effect/computed), use reactive theme signal
+    // Otherwise, use the static getCurrentTheme for backward compatibility with tests
+    const isInReactiveContext = getCurrentComputation() !== null
+    
+    let currentTheme: string
+    if (isInReactiveContext) {
+      // Use reactive theme signal for proper reactivity
+      const themeSignal = getThemeSignal()
+      currentTheme = themeSignal()
+    } else {
+      // Use static theme access for tests and non-reactive contexts
+      currentTheme = ImageAsset.getCurrentTheme()
+    }
+    
+    // Resolve priority: theme-specific → default
+    if (currentTheme === 'dark') {
+      return this.dark || this.default
+    } else {
+      return this.light || this.default
+    }
+  }
+
+  // Additional accessors
+  get src(): string {
+    return this.resolve()
+  }
+
+  get lightSrc(): string {
+    return this.light || this.default
+  }
+
+  get darkSrc(): string {
+    return this.dark || this.default
+  }
+
+  get defaultSrc(): string {
+    return this.default
+  }
+}

package/src/assets/README.md

@@ -0,0 +1,190 @@
+# TachUI Assets System
+
+The Assets system provides a unified way to manage theme-adaptive resources including colors, images, and other design assets in TachUI. It's designed to be similar to SwiftUI's asset management system while leveraging TachUI's reactive architecture.
+
+## Features
+
+- **Theme-Adaptive Assets**: Automatically adapt to light/dark mode
+- **Dot Notation Access**: Clean, intuitive API (`Assets.primaryColor`)
+- **Explicit Theme Access**: Force specific theme variants (`Assets.primaryColor.light`)
+- **Extensible**: Support for custom asset types beyond colors and images
+- **TypeScript Support**: Full type safety with proper interfaces
+- **Performance**: Efficient proxy-based access with caching
+
+## Usage
+
+### Basic Usage
+
+```typescript
+import { Assets, registerAsset, ColorAsset } from '@tachui/core/assets'
+
+// Register custom assets
+registerAsset('primaryColor', ColorAsset.init('#007AFF', '#0A84FF', 'primaryColor'))
+registerAsset('backgroundColor', ColorAsset.init('#FFFFFF', '#1a1a1a', 'backgroundColor'))
+
+// Use assets in components
+import { Text } from '@tachui/core/components'
+
+export function MyComponent() {
+  return Text('Hello World')
+    .modifier
+    .foregroundColor(Assets.primaryColor)  // Auto-adapts to current theme
+    .backgroundColor(Assets.backgroundColor)
+    .build()
+}
+```
+
+### Explicit Theme Access
+
+```typescript
+// Always use light variant
+Text('Always Light').modifier.foregroundColor(Assets.primaryColor.light)
+
+// Always use dark variant
+Text('Always Dark').modifier.foregroundColor(Assets.primaryColor.dark)
+```
+
+### Image Assets
+
+```typescript
+import { ImageAsset } from '@tachui/core/assets'
+
+// Register image assets
+registerAsset('logo', ImageAsset.init('/logo-light.png', '/logo-dark.png', 'logo'))
+
+// Use in components
+import { Image } from '@tachui/core/components'
+
+export function LogoComponent() {
+  return Image(Assets.logo)  // Auto-adapts to current theme
+    .modifier
+    .frame(100, 50)
+    .build()
+}
+```
+
+## Built-in System Assets
+
+TachUI provides built-in system colors that match SwiftUI's color system:
+
+```typescript
+// System colors
+Assets.systemBlue    // #007AFF (light) / #0A84FF (dark)
+Assets.systemGreen   // #34C759 (light) / #30D158 (dark)
+Assets.systemRed     // #FF3B30 (light) / #FF453A (dark)
+Assets.systemOrange  // #FF9500 (light) / #FF9F0A (dark)
+Assets.systemPurple  // #5856D6 (light) / #5E5CE6 (dark)
+Assets.systemPink    // #FF2D55 (light) / #FF375F (dark)
+Assets.systemGray    // #8E8E93 (both)
+Assets.systemBlack   // #000000 (both)
+Assets.systemWhite   // #FFFFFF (both)
+```
+
+## Creating Custom Assets
+
+### Color Assets
+
+```typescript
+import { ColorAsset } from '@tachui/core/assets'
+
+// Create a custom color asset
+const brandPrimary = ColorAsset.init('#FF6B35', '#FF8E6B', 'brandPrimary')
+
+// Register it
+registerAsset('brandPrimary', brandPrimary)
+
+// Use it
+Assets.brandPrimary  // Auto-adapts
+Assets.brandPrimary.light  // Always light
+Assets.brandPrimary.dark   // Always dark
+```
+
+### Image Assets
+
+```typescript
+import { ImageAsset } from '@tachui/core/assets'
+
+// Create a custom image asset
+const heroImage = ImageAsset.init('/hero-light.jpg', '/hero-dark.jpg', 'heroImage', {
+  alt: 'Hero banner image',
+  placeholder: '/placeholder.jpg'
+})
+
+// Register it
+registerAsset('heroImage', heroImage)
+
+// Use it
+Assets.heroImage  // Auto-adapts
+Assets.heroImage.lightSrc  // Always light source
+Assets.heroImage.darkSrc   // Always dark source
+```
+
+## Integration with Modifiers
+
+The Assets system seamlessly integrates with TachUI's modifier system:
+
+```typescript
+import { appearanceModifiers } from '@tachui/core/modifiers/core'
+
+// Use assets with modifiers
+const colorModifier = appearanceModifiers.foregroundColor(Assets.primaryColor)
+const backgroundModifier = appearanceModifiers.backgroundColor(Assets.backgroundColor)
+```
+
+## Advanced Usage
+
+### Asset Bundles
+
+For better organization, you can create logical groupings of assets:
+
+```typescript
+// Create semantic color bundles
+registerAsset('textPrimary', ColorAsset.init('#1a1a1a', '#ffffff', 'textPrimary'))
+registerAsset('textSecondary', ColorAsset.init('#666666', '#cccccc', 'textSecondary'))
+
+registerAsset('backgroundPrimary', ColorAsset.init('#FFFFFF', '#1a1a1a', 'backgroundPrimary'))
+registerAsset('backgroundSecondary', ColorAsset.init('#f8f9fa', '#2a2a2a', 'backgroundSecondary'))
+```
+
+### Custom Asset Types
+
+You can extend the system with custom asset types:
+
+```typescript
+import { Asset } from '@tachui/core/assets'
+
+class GradientAsset extends Asset {
+  constructor(
+    public readonly lightGradient: string,
+    public readonly darkGradient: string,
+    name: string
+  ) {
+    super(name)
+  }
+  
+  resolve(): string {
+    return getCurrentTheme() === 'dark' ? this.darkGradient : this.lightGradient
+  }
+}
+
+// Register custom asset
+registerAsset('primaryGradient', new GradientAsset(
+  'linear-gradient(to right, #007AFF, #5856D6)',
+  'linear-gradient(to right, #0A84FF, #5E5CE6)',
+  'primaryGradient'
+))
+```
+
+## Benefits
+
+1. **SwiftUI Familiarity**: Developers familiar with SwiftUI will feel at home
+2. **Automatic Theme Adaptation**: Colors automatically switch between light/dark modes
+3. **Semantic Naming**: Clear, purpose-driven asset names
+4. **Global Access**: Centralized asset definitions that can be imported anywhere
+5. **Type Safety**: Full TypeScript support with proper interfaces
+6. **Performance**: Reactive updates only when theme changes
+7. **Flexibility**: Developers can define custom palettes while using standard assets
+
+## Implementation Details
+
+The Assets system uses JavaScript Proxies to enable the clean dot notation API while providing automatic theme adaptation. Assets are resolved reactively based on the current theme, ensuring consistent appearance across your application.