Stencil Sass Plugin

import { sass } from "@stencil/sass";

const { sass } = require("@stencil/sass");

import { Config } from "@stencil/core";
import { sass } from "@stencil/sass";

export const config: Config = {
  plugins: [
    sass({
      // Basic configuration
      outputStyle: 'compressed',
      sourceMap: true,
      includePaths: ['src/styles'],
      
      // Stencil-specific: inject global Sass files
      injectGlobalPaths: ['src/styles/variables.scss', 'src/styles/mixins.scss']
    })
  ]
};

/**
 * Creates and configures the Stencil Sass plugin
 * @param opts - Optional configuration options for the plugin
 * @returns Configured Stencil plugin with transform method
 */
function sass(opts?: PluginOptions): Plugin;

// Minimal configuration
sass()

// Basic configuration with output options
sass({
  outputStyle: 'compressed',
  sourceMap: true
})

// Advanced configuration with global injection
sass({
  includePaths: ['src/styles', 'node_modules'],
  injectGlobalPaths: [
    'src/styles/variables.scss',
    'src/styles/mixins.scss'
  ],
  outputStyle: 'expanded',
  sourceMap: true,
  quietDeps: true
})

interface PluginOptions {
  /** Path to a file to compile */
  file?: string;
  
  /** A string to pass to compile (use with includePaths for @import support) */
  data?: string;
  
  /** Custom importer functions for handling @import directives */
  importer?: Importer | Importer[];
  
  /** Custom functions that may be invoked by Sass files */
  functions?: { [key: string]: (...args: any[]) => any };
  
  /** Paths for @import resolution */
  includePaths?: string[];
  
  /** Global Sass files to inject (Stencil-specific feature) */
  injectGlobalPaths?: string[];
  
  /** Enable Sass indented syntax for parsing */
  indentedSyntax?: boolean;
  
  /** Indentation character type */
  indentType?: 'space' | 'tab';
  
  /** Number of spaces/tabs for indentation */
  indentWidth?: number;
  
  /** Line break sequence */
  linefeed?: 'cr' | 'crlf' | 'lf' | 'lfcr';
  
  /** Disable source map URL inclusion in output */
  omitSourceMapUrl?: boolean;
  
  /** Output file location for source maps */
  outFile?: string;
  
  /** CSS output format */
  outputStyle?: 'compressed' | 'expanded';
  
  /** Suppress dependency warnings */
  quietDeps?: boolean;
  
  /** Silence specific deprecation warnings */
  silenceDeprecations?: DeprecationOrId[];
  
  /** Enable source map generation */
  sourceMap?: boolean | string;
  
  /** Include contents in source map */
  sourceMapContents?: boolean;
  
  /** Embed source map as data URI */
  sourceMapEmbed?: boolean;
  
  /** Source map root value */
  sourceMapRoot?: string;
}

/**
 * Function type for custom Sass importers
 * @param url - The URL/path being imported
 * @param prev - The stylesheet that contained the @import
 * @param done - Callback to return the import result
 * @returns Import result or void (for async handling via callback)
 */
type Importer = (
  url: string,
  prev: string,
  done: (data: ImporterReturnType) => void
) => ImporterReturnType | void;

/**
 * Return type for importer functions
 */
type ImporterReturnType = 
  | { file: string }      // Return file path to load
  | { contents: string }  // Return contents directly
  | Error                 // Return error
  | null;                 // Unable to handle this import

sass({
  importer: [
    // Custom importer for special prefixes
    (url, prev, done) => {
      if (url.startsWith('theme:')) {
        const themePath = `src/themes/${url.substring(6)}.scss`;
        done({ file: themePath });
        return;
      }
      done(null); // Let default importer handle it
    }
  ]
})

sass({
  injectGlobalPaths: [
    'src/styles/variables.scss',
    'src/styles/mixins.scss'
  ]
})

// Import from node_modules
@import '~bootstrap/scss/variables';
@import '~@angular/material/theming';

sass({
  // Expanded output for easier CSS debugging
  outputStyle: 'expanded',
  
  // Enable source maps with full content for debugging
  sourceMap: true,
  sourceMapContents: true,
  
  // Include both project styles and node_modules for imports
  includePaths: ['src/styles', 'node_modules'],
  
  // Inject development-specific variables
  injectGlobalPaths: ['src/styles/dev-variables.scss']
})

sass({
  // Compressed output for smaller CSS bundles
  outputStyle: 'compressed',
  
  // Disable source maps in production
  sourceMap: false,
  
  // Suppress dependency warnings to reduce noise
  quietDeps: true,
  
  // Silence legacy API deprecation warnings
  silenceDeprecations: ['legacy-js-api'],
  
  // Only include necessary paths
  includePaths: ['src/styles'],
  
  // Inject only production variables and mixins
  injectGlobalPaths: ['src/styles/variables.scss', 'src/styles/mixins.scss']
})

sass({
  functions: {
    'get-theme-color($name)': (name: any) => {
      const colors = {
        primary: '#007bff',
        secondary: '#6c757d'
      };
      return colors[name.getValue()] || '#000000';
    }
  }
})

/**
 * Stencil plugin interface (re-exported from @stencil/core)
 */
interface Plugin {
  name: string;
  pluginType: string;
  transform?: (sourceText: string, fileName: string, context: PluginCtx) => Promise<PluginTransformResults>;
}

/**
 * Plugin transformation results
 */
interface PluginTransformResults {
  id: string;
  code?: string;
  dependencies?: string[];
}

/**
 * Plugin context provided by Stencil
 */
interface PluginCtx {
  config: Config;
  fs: FileSystem;
  sys: System;
  diagnostics: Diagnostic[];
}

/**
 * Deprecation identifier type from sass-embedded
 */
type DeprecationOrId = string | { id: string };