igniteui-theming/dist/mcp/utils/sass.d.ts

A set of Sass variables, mixins, and functions for generating palettes, typography, and elevations used by Ignite UI components.

import { ColorDefinition, GrayDefinition, Platform, ThemeVariant } from './types.js';
/**
 * Properly quote a font-family value for Sass.
 * Font stacks (containing commas) need to be wrapped in quotes
 * to preserve them as a single string value.
 *
 * Handles various input formats:
 * - `Roboto` -> `'Roboto'`
 * - `'Roboto'` -> `'Roboto'` (unchanged)
 * - `'Titillium Web', sans-serif` -> `"'Titillium Web', sans-serif"`
 * - `"Titillium Web", sans-serif` -> `'"Titillium Web", sans-serif'`
 */
export declare function quoteFontFamily(typeface: string): string;
/**
 * Convert a name to a valid Sass variable name.
 *
 * Transforms input string to lowercase, replaces invalid characters with hyphens,
 * collapses multiple hyphens, and removes leading/trailing hyphens.
 *
 * @param name - The name to convert
 * @returns A valid Sass variable name (without $ prefix)
 * @throws Error if the input results in an empty variable name
 *
 * @example
 * toVariableName('My Theme') // 'my-theme'
 * toVariableName('DARK_THEME_v2') // 'dark-theme-v2'
 */
export declare function toVariableName(name: string): string;
/**
 * Generate a comment header for generated Sass code.
 *
 * @param description - Description of what the code does
 * @returns Formatted Sass comment header
 */
export declare function generateHeader(description: string): string;
/** Inline comment prepended above @use lines in generated Sass. */
export declare const SASS_USE_INLINE_COMMENT = "// NOTE: @use rules must be at the top of the file. Deduplicate when combining multiple outputs.";
/** Markdown assembly note appended after Sass code blocks in handler responses. */
export declare const SASS_USE_ASSEMBLY_NOTE = "\n> **File placement:** `@use` rules must appear at the very top of the `.scss` file, before any other statements. When combining outputs from multiple tools, keep only one `@use` per module path.";
/**
 * Generate the Sass @use statement for the theming library.
 * Uses platform-specific import paths when platform is specified.
 *
 * @param platform - Target platform (angular or webcomponents)
 * @param licensed - Whether to use the licensed @infragistics package (Angular only, defaults to false)
 * @returns The inline placement comment + @use statement for the platform
 */
export declare function generateUseStatement(platform?: Platform, licensed?: boolean): string;
/**
 * Generate additional @use import statements for typography and/or elevation presets.
 *
 * For non-Angular platforms, preset variables like `$material-type-scale` and
 * `$material-elevations` are defined in separate sub-modules that must be
 * explicitly imported. Angular's `igniteui-angular/theming` re-exports all
 * presets, so no additional imports are needed.
 *
 * These imports use the presets index files which re-forward individual
 * design system modules with prefixed names (e.g., `$type-scale` becomes
 * `$material-type-scale` via `@forward './material' as material-*`).
 *
 * @param options - Configuration for which preset imports to include
 * @returns Array of @use statements (empty for Angular)
 */
export declare function generatePresetImports(options: {
    platform?: Platform;
    includeTypography?: boolean;
    includeElevations?: boolean;
}): string[];
/**
 * Options for generating a palette function call.
 */
export interface PaletteCodeOptions {
    /** Primary brand color */
    primary: string;
    /** Secondary/accent color (required by Sass palette function) */
    secondary: string;
    /** Surface/background color (required by Sass palette function) */
    surface: string;
    /** Gray base color */
    gray?: string;
    /** Info state color */
    info?: string;
    /** Success state color */
    success?: string;
    /** Warning state color */
    warn?: string;
    /** Error state color */
    error?: string;
    /** Theme variant (affects surface default) */
    variant?: ThemeVariant;
    /** Variable name for the palette (without $) */
    variableName?: string;
    /** Whether to use inline color values or reference Sass variables */
    useVariableReferences?: boolean;
}
/**
 * Result from generating palette code.
 */
export interface PaletteCodeResult {
    /** Lines for color variable declarations (if useVariableReferences is true) */
    colorVariables: string[];
    /** Lines for the palette() function call */
    paletteDefinition: string[];
    /** The full variable name (with $) */
    variableName: string;
}
/**
 * Generate the palette() function call code.
 * Returns an object with code lines that can be joined or embedded in other code.
 *
 * @example
 * // Basic usage - returns lines for palette definition
 * const result = generatePaletteCode({ primary: '#2ab759' });
 * // result.paletteDefinition: ['$custom-light-palette: palette(', '  $primary: #2ab759,', '  $surface: white', ');']
 *
 * @example
 * // With variable references (for use in theme generators)
 * const result = generatePaletteCode({
 *   primary: '#2ab759',
 *   useVariableReferences: true,
 *   variableName: 'my-palette'
 * });
 * // Uses $primary-color, $secondary-color references
 */
export declare function generatePaletteCode(options: PaletteCodeOptions): PaletteCodeResult;
/**
 * Options for generating a typography mixin call.
 */
export interface TypographyCodeOptions {
    /** Font family string */
    fontFamily: string;
    /** Type scale variable name (with $) */
    typeScaleVar: string;
    /** Indentation for the mixin call */
    indent?: string;
}
/**
 * Generate the typography() mixin call code.
 * Returns an array of lines that can be joined or embedded in other code.
 */
export declare function generateTypographyCode(options: TypographyCodeOptions): string[];
/**
 * Options for generating an elevations mixin call.
 */
export interface ElevationsCodeOptions {
    /** Elevations variable name (with $) */
    elevationsVar: string;
    /** Indentation for the mixin call */
    indent?: string;
}
/**
 * Generate the elevations() mixin call code.
 * Returns an array of lines that can be joined or embedded in other code.
 */
export declare function generateElevationsCode(options: ElevationsCodeOptions): string[];
/**
 * Options for generating a custom handmade palette.
 */
export interface CustomPaletteCodeOptions {
    /** Target platform (affects import statements) */
    platform?: Platform;
    /** Theme variant (light or dark) */
    variant?: ThemeVariant;
    /** Variable name for the palette (without $ prefix) */
    variableName?: string;
    /** Surface color for gray shades generation */
    surfaceColor?: string;
    /** Color definitions for all palette groups */
    colors: {
        primary: ColorDefinition;
        secondary: ColorDefinition;
        surface: ColorDefinition;
        gray: GrayDefinition;
        info: ColorDefinition;
        success: ColorDefinition;
        warn: ColorDefinition;
        error: ColorDefinition;
    };
}
/**
 * Generates Sass code for a custom handmade palette.
 *
 * This function creates a Sass map palette structure that can use either:
 * - The `shades()` function for auto-generating shades from a base color
 * - Explicit shade maps with manual control over each shade value
 *
 * @example
 * // Generate palette with mixed modes
 * const lines = generateCustomPaletteCode({
 *   variant: 'light',
 *   variableName: 'my-brand',
 *   surfaceColor: '#fafafa',
 *   colors: {
 *     primary: { mode: 'explicit', shades: { '50': '#e6eff8', ... } },
 *     secondary: { mode: 'shades', baseColor: '#f7bd32' },
 *     // ...
 *   }
 * });
 */
export declare function generateCustomPaletteCode(options: CustomPaletteCodeOptions): string[];