transform.ts

/*
 * Copyright (c) 2024, Salesforce, Inc.
 * All rights reserved.
 * SPDX-License-Identifier: MIT
 * For full license text, see the LICENSE file in the repo root or https://opensource.org/licenses/MIT
 */
import postcss from 'postcss';
import { getAPIVersionFromNumber } from '@lwc/shared';

import serialize from './serialize';
import postcssLwc from './postcss-lwc-plugin';
import { StyleCompilerCtx } from './utils/error-recovery';

/** Configuration options for CSS transforms. */
export interface Config {
    /**
     * CSS custom properties configuration
     * @deprecated Custom property transforms are deprecated because IE11 and other legacy browsers are no longer supported.
     */
    // TODO [#3266]: Remove StylesheetConfig as part of breaking change wishlist
    customProperties?: {
        /** Name of the module to resolve custom properties lookup */
        resolverModule?: string;
    };
    /** Token that is used for scoping in light DOM scoped styles */
    scoped?: boolean;
    /** When set to true, synthetic shadow DOM support is removed from the output JavaScript */
    disableSyntheticShadowSupport?: boolean;
    /** The API version to associate with the compiled stylesheet */
    apiVersion?: number;
    /** When set to true, enables error recovery mode to collect multiple errors */
    experimentalErrorRecoveryMode?: boolean;
}

/**
 * Transforms CSS for use with LWC components.
 * @param src Contents of the CSS source file
 * @param id Filename of the CSS source file
 * @param config Transformation options
 * @returns Transformed CSS
 * @example
 * import { transform } from '@lwc/style-compiler';
 * const source = `
 *  :host {
 *    opacity: 0.4;
 *  }
 *  span {
 *    text-transform: uppercase;
 *  }`;
 * const { code } = transform(source, 'example.css');
 */
export function transform(
    src: string,
    id: string,
    config: Config = {}
): { code: string; errors?: Error[] } {
    if (src === '') {
        return { code: 'export default undefined' };
    }

    const scoped = !!config.scoped;
    const apiVersion = getAPIVersionFromNumber(config.apiVersion);
    const disableSyntheticShadowSupport = !!config.disableSyntheticShadowSupport;
    const errorRecoveryMode = !!config.experimentalErrorRecoveryMode;

    // Create error recovery context
    const ctx = new StyleCompilerCtx(errorRecoveryMode, id);

    const plugins = [
        postcssLwc({
            scoped,
            apiVersion,
            disableSyntheticShadowSupport,
            ctx,
        }),
    ];

    // Wrap PostCSS processing with error recovery for parsing errors
    let result;
    try {
        result = postcss(plugins).process(src, { from: id }).sync();
    } catch (error) {
        if (errorRecoveryMode && error instanceof postcss.CssSyntaxError) {
            ctx.errors.push(error);
            // eslint-disable-next-line preserve-caught-error
            throw AggregateError(ctx.errors);
        } else {
            throw error;
        }
    }

    if (errorRecoveryMode && ctx.hasErrors()) {
        throw AggregateError(ctx.errors);
    }

    return { code: serialize(result, config) };
}