CSS Compilation

/**
 * Compiles CSS with Tailwind CSS processing
 * @param css - CSS string to compile (typically containing @tailwind directives)
 * @param options - Compilation configuration options
 * @returns Promise resolving to a Compiler instance
 */
function compile(css: string, options: CompileOptions): Promise<Compiler>;

interface CompileOptions {
  /** Base directory for resolving relative paths */
  base: string;
  /** Source file path for better error reporting */
  from?: string;
  /** Callback invoked for each discovered dependency */
  onDependency: (path: string) => void;
  /** Whether to rewrite relative URLs in CSS */
  shouldRewriteUrls?: boolean;
  /** CSS polyfill configuration */
  polyfills?: Polyfills;
  /** Custom resolver for CSS imports */
  customCssResolver?: Resolver;
  /** Custom resolver for JavaScript/TypeScript modules */
  customJsResolver?: Resolver;
}

interface Compiler {
  /** Generates the final CSS output */
  build(): string;
  /** Source detection configuration (if any) */
  root?: { pattern: string } | 'none';
}

import { compile, CompileOptions } from "@tailwindcss/node";

// Basic compilation
const compiler = await compile(`
  @tailwind base;
  @tailwind components;
  @tailwind utilities;
`, {
  base: process.cwd(),
  onDependency: (path) => console.log("Dependency:", path)
});

const css = compiler.build();

// Advanced compilation with custom resolvers
const advancedCompiler = await compile(`
  @import "./components.css";
  @tailwind utilities;
`, {
  base: "/path/to/project",
  from: "/path/to/project/src/styles.css",
  onDependency: (path) => {
    // Track dependencies for hot reloading
    watchedFiles.add(path);
  },
  shouldRewriteUrls: true,
  customCssResolver: async (id, base) => {
    // Custom CSS resolution logic
    if (id.startsWith("@/")) {
      return path.resolve(base, "src", id.slice(2));
    }
    return undefined;
  }
});

/**
 * Compiles AST nodes with Tailwind CSS processing
 * @param ast - Array of parsed AST nodes
 * @param options - Compilation configuration options
 * @returns Promise resolving to a Compiler instance
 */
function compileAst(ast: AstNode[], options: CompileOptions): Promise<Compiler>;

interface AstNode {
  // AST node structure (implementation details from tailwindcss package)
}

/**
 * Loads a JavaScript/TypeScript module with dependency tracking
 * @param id - Module identifier (relative or package name)
 * @param base - Base directory for resolution
 * @param onDependency - Callback for each discovered dependency
 * @param customJsResolver - Optional custom module resolver
 * @returns Promise resolving to module information
 */
function loadModule(
  id: string,
  base: string,
  onDependency: (path: string) => void,
  customJsResolver?: Resolver
): Promise<ModuleResult>;

interface ModuleResult {
  /** Absolute path to the loaded module */
  path: string;
  /** Directory containing the module */
  base: string;
  /** The loaded module's exports */
  module: any;
}

import { loadModule } from "@tailwindcss/node";

// Load a config file
const configModule = await loadModule(
  "./tailwind.config.js",
  process.cwd(),
  (path) => console.log("Config dependency:", path)
);

const config = configModule.module;

// Load with custom resolver
const themeModule = await loadModule(
  "@/theme",
  "/path/to/project",
  (path) => dependencies.add(path),
  async (id, base) => {
    if (id.startsWith("@/")) {
      return path.resolve(base, "src", id.slice(2));
    }
    return undefined;
  }
);

/**
 * Loads design system configuration (unstable API)
 * @param css - CSS containing design system definitions
 * @param options - Configuration with base directory
 * @returns Promise resolving to design system configuration
 */
function __unstable__loadDesignSystem(
  css: string, 
  options: { base: string }
): Promise<DesignSystem>;

interface DesignSystem {
  // Design system structure (implementation details may change)
}

/**
 * Custom resolver function for modules or CSS files
 * @param id - The identifier to resolve
 * @param base - Base directory for resolution
 * @returns Promise resolving to resolved path, false if not found, or undefined to defer to default resolver
 */
type Resolver = (id: string, base: string) => Promise<string | false | undefined>;

/** CSS feature flags for compilation control */
enum Features {
  // Specific feature values are defined in the tailwindcss package
}

/** CSS polyfill configuration options */
interface Polyfills {
  // Polyfill options are defined in the tailwindcss package
}

// Global functions that can be defined to customize behavior
declare global {
  var __tw_readFile: ((path: string, encoding: string) => Promise<string | null>) | undefined;
  var __tw_load: ((path: string) => Promise<any | null>) | undefined;
  var __tw_resolve: ((id: string, base: string) => string | null) | undefined;
}