Plugin Configuration

/**
 * Creates a PostCSS preset environment plugin
 * @param options - Configuration options for the plugin
 * @returns PostCSS plugin instance
 */
declare function postcssPresetEnv(options?: pluginOptions): PostCSS.Plugin;

// Basic usage with default stage 2 features
const plugin = postcssPresetEnv();

// Target specific browsers
const plugin = postcssPresetEnv({
  browsers: ['> 1%', 'last 2 versions']
});

// Enable all stage 3 features
const plugin = postcssPresetEnv({
  stage: 3
});

// Disable autoprefixer
const plugin = postcssPresetEnv({
  autoprefixer: false
});

interface StageOptions {
  /**
   * Determine which CSS features to polyfill based on standardization stage
   * - Stage 0: Experimental features
   * - Stage 1: Working draft features
   * - Stage 2: Candidate recommendation (default)
   * - Stage 3: Recommendation features
   * - Stage 4: Web standard features
   * - false: Disable stage-based feature selection
   */
  stage?: number | false;
  
  /**
   * Minimum number of vendor implementations required for a feature
   * Features with fewer implementations will be skipped
   * @default 0
   */
  minimumVendorImplementations?: number;
}

// Only use well-established features (stage 3+)
postcssPresetEnv({ stage: 3 });

// Use experimental features (stage 0+)
postcssPresetEnv({ stage: 0 });

// Disable stage filtering, rely on browser support only
postcssPresetEnv({ stage: false });

// Require at least 2 vendor implementations
postcssPresetEnv({ minimumVendorImplementations: 2 });

interface BrowserTargeting {
  /**
   * Browserslist environment name for multi-environment configs
   * Used when .browserslistrc or package.json has multiple environments
   */
  env?: string;
  
  /**
   * Override browser targets directly
   * When specified, ignores .browserslistrc and package.json browserslist
   * Takes precedence over env option
   */
  browsers?: string | string[] | null;
}

// Use specific browserslist environment
postcssPresetEnv({ env: 'production' });

// Override browser targets
postcssPresetEnv({
  browsers: ['> 1%', 'last 2 versions', 'Firefox ESR']
});

// Support only modern browsers
postcssPresetEnv({
  browsers: ['last 1 Chrome version', 'last 1 Firefox version']
});

interface PreservationOptions {
  /**
   * Global preserve setting for all plugins
   * Individual plugins may override this default
   * When undefined, each plugin uses its own default
   */
  preserve?: boolean;
}

// Preserve original CSS alongside polyfills
postcssPresetEnv({ preserve: true });

// Remove original CSS, keep only polyfills
postcssPresetEnv({ preserve: false });

interface AutoprefixerOptions {
  /**
   * Autoprefixer configuration or false to disable
   * Shares browser targets with the main plugin
   * @default autoprefixer enabled with shared targets
   */
  autoprefixer?: autoprefixer.Options | false;
}

// Disable autoprefixer
postcssPresetEnv({ autoprefixer: false });

// Configure autoprefixer options
postcssPresetEnv({
  autoprefixer: {
    grid: 'autoplace',
    remove: false
  }
});

interface PluginInsertion {
  /**
   * Insert plugins before specific features
   * Key is feature ID, value is plugin or array of plugins
   */
  insertBefore?: Record<string, unknown>;
  
  /**
   * Insert plugins after specific features
   * Key is feature ID, value is plugin or array of plugins
   */
  insertAfter?: Record<string, unknown>;
}

import customPlugin from 'my-custom-plugin';

postcssPresetEnv({
  insertBefore: {
    'custom-properties': customPlugin()
  },
  insertAfter: {
    'nesting-rules': [plugin1(), plugin2()]
  }
});

interface DebugOptions {
  /**
   * Enable debug output showing which features are enabled/disabled
   * Logs to PostCSS result messages
   * @default false
   */
  debug?: boolean;
  
  /**
   * Enable client-side polyfills requiring runtime JavaScript
   * Most features work with CSS-only transforms
   * @default false
   */
  enableClientSidePolyfills?: boolean;
}

// Enable debug logging
postcssPresetEnv({ debug: true });

// Enable features requiring client-side JavaScript
postcssPresetEnv({ enableClientSidePolyfills: true });

interface LogicalConfiguration {
  /**
   * Configure logical properties behavior globally
   * Affects all logical property plugins at once
   */
  logical?: {
    /** Set the inline flow direction (default: left-to-right) */
    inlineDirection?: DirectionFlow;
    /** Set the block flow direction (default: top-to-bottom) */
    blockDirection?: DirectionFlow;
  };
}

// Configure right-to-left layout
postcssPresetEnv({
  logical: {
    inlineDirection: 'right-to-left',
    blockDirection: 'top-to-bottom'
  }
});

interface pluginOptions {
  stage?: number | false;
  minimumVendorImplementations?: number;
  enableClientSidePolyfills?: boolean;
  env?: string;
  browsers?: string | string[] | null;
  preserve?: boolean;
  autoprefixer?: autoprefixer.Options | false;
  features?: pluginsOptions;
  insertBefore?: Record<string, unknown>;
  insertAfter?: Record<string, unknown>;
  debug?: boolean;
  logical?: {
    inlineDirection?: DirectionFlow;
    blockDirection?: DirectionFlow;
  };
}