@visulima/rollup-plugin-css 1.0.0-alpha.30 → 1.0.0-alpha.31

package/dist/utils/options.d.ts

@@ -0,0 +1,155 @@
+import type { RollupLogger } from "@visulima/packem-share/utils";
+import type { Result } from "postcss-load-config";
+import type { LoaderContext } from "../loaders/types.d.ts";
+import type { InternalStyleOptions, PostCSSOptions, StyleOptions } from "../types.d.ts";
+/**
+ * Internal mode configuration for style processing.
+ *
+ * Represents the resolved mode options that determine how CSS is handled:
+ * - emit: Output raw CSS for further processing
+ * - extract: Extract CSS to separate files
+ * - inject: Inject CSS into JavaScript at runtime
+ */
+interface Mode {
+    /** Whether to emit raw CSS for further processing */
+    emit: InternalStyleOptions["emit"];
+    /** Whether to extract CSS to separate files (boolean or filename) */
+    extract: InternalStyleOptions["extract"];
+    /** Whether to inject CSS at runtime (boolean or injection options) */
+    inject: InternalStyleOptions["inject"];
+    /** Whether to inline CSS as strings in JavaScript */
+    inline: InternalStyleOptions["inline"];
+}
+/** PostCSS option types for error messages */
+type PCSSOption = "parser" | "plugin" | "stringifier" | "syntax";
+/**
+ * Infers and validates the CSS processing mode from user options.
+ *
+ * Converts the user-provided mode configuration into internal mode settings.
+ * Supports both simple string modes and tuple modes with additional options.
+ * @param mode User-provided mode configuration
+ * @returns Resolved mode configuration object
+ * @throws Error if an invalid mode is provided
+ * @example
+ * ```typescript
+ * // Simple mode
+ * inferModeOption('extract') // { emit: false, extract: true, inject: false }
+ *
+ * // Mode with options
+ * inferModeOption(['inject', { singleTag: true }])
+ * // { emit: false, extract: false, inject: { singleTag: true } }
+ *
+ * // Default mode (inject)
+ * inferModeOption(undefined) // { emit: false, extract: false, inject: true }
+ * ```
+ */
+export declare const inferModeOption: (mode: StyleOptions["mode"]) => Mode;
+/**
+ * Infers option values from boolean or object configurations.
+ *
+ * This utility handles the common pattern where options can be:
+ * - `true`: Enable with default settings (returns empty object)
+ * - `false`: Disable the option (returns false)
+ * - `object`: Use the provided configuration
+ * - `undefined`: Use the provided default value
+ * @param option The option value to process
+ * @param defaultValue Default value when option is undefined
+ * @returns Processed option value
+ * @example
+ * ```typescript
+ * inferOption(true, {}) // {}
+ * inferOption(false, {}) // false
+ * inferOption({ custom: 'value' }, {}) // { custom: 'value' }
+ * inferOption(undefined, { default: true }) // { default: true }
+ * ```
+ */
+export declare const inferOption: <T, TDefine extends T | boolean | undefined>(option: T | boolean | undefined, defaultValue: TDefine) => OptionType<T, TDefine>;
+/**
+ * Infers source map configuration from user options.
+ *
+ * Processes source map options which can be specified as:
+ * - `boolean`: Enable/disable with default settings
+ * - `"inline"`: Enable with inline source maps
+ * - `[boolean | "inline", SourceMapOptions]`: Enable with custom options
+ * @param sourceMap User-provided source map configuration
+ * @returns Processed source map configuration for loaders
+ * @example
+ * ```typescript
+ * inferSourceMapOption(true) // { content: true, inline: false }
+ * inferSourceMapOption('inline') // { content: true, inline: true }
+ * inferSourceMapOption([true, { transform: fn }]) // { content: true, inline: false, transform: fn }
+ * inferSourceMapOption(false) // false
+ * ```
+ */
+export declare const inferSourceMapOption: (sourceMap: StyleOptions["sourceMap"]) => LoaderContext["sourceMap"];
+/**
+ * Infers handler options that support alias configuration.
+ *
+ * Processes options for handlers (like import/url resolvers) that can use aliases.
+ * If aliases are provided and the option doesn't already have aliases, they are merged.
+ * @param option Handler option configuration
+ * @param alias Path aliases to merge if not already present
+ * @returns Processed handler option with aliases
+ * @example
+ * ```typescript
+ * const aliases = { '@': '/src' };
+ *
+ * inferHandlerOption(true, aliases) // { alias: { '@': '/src' } }
+ * inferHandlerOption({ custom: true }, aliases) // { custom: true, alias: { '@': '/src' } }
+ * inferHandlerOption({ alias: { '~': '/lib' } }, aliases) // { alias: { '~': '/lib' } }
+ * ```
+ */
+export declare const inferHandlerOption: <T extends {
+    alias?: Record<string, string>;
+}>(option: T | boolean | undefined, alias: T["alias"]) => T | false;
+/**
+ * Ensures a PostCSS option is properly loaded and resolved.
+ *
+ * PostCSS options can be specified as strings (module names) or objects.
+ * This function loads string-based options as modules and validates they exist.
+ * @param option PostCSS option (string module name or object)
+ * @param type Type of PostCSS option for error messages
+ * @param cwd Current working directory for module resolution
+ * @param logger Optional logger for warnings
+ * @returns Promise resolving to the loaded PostCSS option
+ * @throws Error if string module cannot be loaded
+ * @example
+ * ```typescript
+ * // Load parser module
+ * await ensurePCSSOption('sugarss', 'parser', process.cwd()) // Loaded sugarss module
+ *
+ * // Pass through object
+ * await ensurePCSSOption(parserObject, 'parser', process.cwd()) // parserObject
+ * ```
+ */
+export declare const ensurePCSSOption: <T>(option: T | string, type: PCSSOption, cwd: string, logger: RollupLogger) => Promise<T>;
+/**
+ * Ensures PostCSS plugins are properly loaded and configured.
+ *
+ * PostCSS plugins can be specified in various formats:
+ * - String module names
+ * - Plugin objects
+ * - Arrays of [plugin, options]
+ * - Mixed arrays of the above
+ *
+ * This function normalizes all formats and loads string-based plugins as modules.
+ * @param plugins PostCSS plugins configuration
+ * @param cwd Current working directory for module resolution
+ * @param logger Optional logger for warnings
+ * @returns Promise resolving to array of loaded PostCSS plugins
+ * @example
+ * ```typescript
+ * // Load plugins from various formats
+ * await ensurePCSSPlugins([
+ *   'autoprefixer',                    // String module name
+ *   ['cssnano', { preset: 'default' }], // Plugin with options
+ *   pluginObject                       // Direct plugin object
+ * ], process.cwd())
+ * ```
+ */
+export declare const ensurePCSSPlugins: (plugins: PostCSSOptions["plugins"], cwd: string, logger: RollupLogger) => Promise<Result["plugins"]>;
+/**
+ * Type alias for option function return types
+ */
+export type OptionType<T, TDefine extends T | boolean | undefined> = T | TDefine | false;
+export {};

package/dist/utils/resolve.d.ts

@@ -0,0 +1,35 @@
+import type { NapiResolveOptions } from "oxc-resolver";
+/**
+ * Resolves module identifiers using advanced resolution strategies.
+ *
+ * This function implements sophisticated module resolution logic using the OXC resolver,
+ * supporting various resolution strategies and providing detailed error reporting.
+ * It's primarily used for resolving CSS imports, PostCSS plugins, and other dependencies.
+ *
+ * Features:
+ * - Multiple base directory support
+ * - Configurable file extensions
+ * - Symlink resolution
+ * - Detailed error reporting and debugging
+ * - Fallback resolution strategies
+ * @param ids Array of module identifiers to resolve
+ * @param userOptions Resolution configuration options
+ * @returns Absolute path to the resolved module
+ * @throws Error if no module can be resolved
+ * @example
+ * ```typescript
+ * // Resolving a PostCSS plugin
+ * const pluginPath = resolve(['autoprefixer'], {
+ *   caller: 'PostCSS',
+ *   baseDirs: ['/project/node_modules'],
+ *   extensions: ['.js', '.mjs']
+ * });
+ * ```
+ */
+export declare const resolve: (ids: string[], userOptions: ResolveOptions) => string;
+export interface ResolveOptions extends NapiResolveOptions {
+    /** directories to begin resolving from (defaults to `[__dirname]`) */
+    baseDirs?: string[];
+    /** name of the caller for error message (default to `Resolver`) */
+    caller?: string;
+}

package/dist/utils/safe-id.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Generates a safe, unique JavaScript identifier from an input string.
+ *
+ * Creates a legal JavaScript identifier by:
+ * 1. Combining the input ID with a salt and additional salt parameters
+ * 2. Generating a hash of the combined string
+ * 3. Appending the hash to the ID to ensure uniqueness
+ * 4. Making the result a legal JavaScript identifier
+ *
+ * This is useful for generating variable names that won't conflict with
+ * reserved words or other identifiers in the generated code.
+ * @param id Base identifier string
+ * @param salt Additional salt values for uniqueness
+ * @returns Legal JavaScript identifier with hash suffix
+ * @example
+ * ```typescript
+ * safeId('myVar') // "myVar_a1b2c3d4"
+ * safeId('class', 'module') // "class_e5f6g7h8"
+ * safeId('my-component', 'css') // "my_component_i9j0k1l2"
+ * ```
+ */
+declare const safeId: (id: string, ...salt: string[]) => string;
+export default safeId;

package/dist/utils/sourcemap.d.ts

@@ -0,0 +1,42 @@
+import type { RawSourceMap } from "source-map-js";
+import { SourceMapConsumer } from "source-map-js";
+declare class MapModifier {
+    private readonly map?;
+    constructor(map?: RawSourceMap | string);
+    modify(f: (m: RawSourceMap) => void): this;
+    modifySources(op: (source: string) => string): this;
+    resolve(directory?: string): this;
+    relative(directory?: string): this;
+    toObject(): RawSourceMap | undefined;
+    toString(): string | undefined;
+    toConsumer(): SourceMapConsumer | undefined;
+    toCommentData(): string;
+    toCommentFile(fileName: string): string;
+}
+export declare const getMap: (code: string, id?: string) => Promise<string | undefined>;
+export declare const stripMap: (code: string) => string;
+/**
+ * Creates a MapModifier instance for source map manipulation.
+ *
+ * This utility function provides a convenient way to create MapModifier instances
+ * for working with source maps in CSS processing pipelines. The MapModifier class
+ * offers comprehensive source map manipulation capabilities including:
+ * - Path resolution and relativization
+ * - Source map merging and modification
+ * - Format conversion (object, string, consumer)
+ * - Comment generation for inline or external maps
+ * @param map Source map input (raw object or JSON string)
+ * @returns MapModifier instance for source map operations
+ * @example
+ * ```typescript
+ * // Working with source map objects
+ * const modifier = mm(rawSourceMap);
+ * modifier.resolve('/project/src').relative('/project');
+ *
+ * // Converting to different formats
+ * const mapString = modifier.toString();
+ * const consumer = modifier.toConsumer();
+ * ```
+ */
+export declare const mm: (map?: RawSourceMap | string) => MapModifier;
+export {};

package/dist/utils/url.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Checks if the URL starts with a tilde followed by a digit, '@', or a letter (case-insensitive)
+ * @param url
+ * @returns
+ */
+export declare const hasModuleSpecifier: (url: string) => boolean;
+export declare const getUrlOfPartial: (url: string) => string;
+export declare const normalizeUrl: (url: string) => string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@visulima/rollup-plugin-css",
-  "version": "1.0.0-alpha.30",
+  "version": "1.0.0-alpha.31",
   "description": "CSS processing plugin for packem",
   "keywords": [
     "visulima",
@@ -97,10 +97,10 @@
   ],
   "dependencies": {
     "@rollup/pluginutils": "5.3.0",
-    "@visulima/fs": "4.1.0",
-    "@visulima/package": "4.1.7",
-    "@visulima/packem-share": "1.0.0-alpha.31",
-    "@visulima/path": "2.0.5",
+    "@visulima/fs": "5.0.0-alpha.12",
+    "@visulima/package": "5.0.0-alpha.11",
+    "@visulima/packem-share": "1.0.0-alpha.32",
+    "@visulima/path": "3.0.0-alpha.10",
     "mlly": "1.8.2",
     "oxc-resolver": "11.19.1",
     "p-queue": "9.1.2",

package/dist/packem_shared/types-B7InbTq8.d.ts

@@ -1,206 +0,0 @@
-import { Options } from 'cssnano';
-import { TransformOptions, CustomAtRules } from 'lightningcss';
-import { Node, AcceptedPlugin, PluginCreator } from 'postcss';
-import { Config } from 'postcss-load-config';
-import { Environment } from '@visulima/packem-share/types';
-import { StringOptions as StringOptions$1 } from 'sass';
-import { StringOptions } from 'sass-embedded';
-import { RenderOptions } from 'stylus';
-import { RollupLogger } from '@visulima/packem-share/utils';
-import { PluginContext, CustomPluginOptions } from 'rollup';
-import { RawSourceMap } from 'source-map-js';
-
-type LESSLoaderOptions = Less.Options;
-
-type ImportResolve = (url: string, basedir: string, extensions: string[], atRule: Node) => Promise<string> | string;
-
-interface ImportOptions {
-    alias: Record<string, string>;
-    debug?: boolean;
-    extensions: string[];
-    filter?: (id: string) => boolean;
-    load: (filename: string, importOptions: ImportOptions) => Promise<string> | string;
-    plugins: AcceptedPlugin[];
-    resolve: ImportResolve;
-    skipDuplicates?: boolean | undefined;
-    warnOnEmpty?: boolean;
-}
-
-interface ModulesOptions {
-    exportGlobals?: boolean;
-    failOnWrongOrder?: boolean;
-    generateScopedName?: string | ((name: string, file: string, css: string) => string);
-    include?: AutoModules;
-    mode?: "global" | "local" | "pure";
-}
-
-interface UrlFile {
-    from: string;
-    source: Uint8Array;
-    urlQuery?: string;
-}
-type UrlResolve = (inputUrl: string, baseDirectories: string[]) => Promise<UrlFile>;
-
-interface UrlOptions {
-    alias?: Record<string, string>;
-    assetDir?: string | ((original: string, resolved: string, file: string) => string);
-    hash?: boolean | string;
-    inline?: boolean;
-    publicPath?: string | ((original: string, resolved: string, file: string) => string);
-    resolve?: UrlResolve;
-}
-
-type SassLoaderContext = {
-    environment: Environment;
-    resourcePath: string;
-    rootContext: string;
-};
-type SassLoaderOptions = {
-    additionalData: string | ((content: string | Buffer, loaderContext: SassLoaderContext) => Promise<string>) | ((content: string | Buffer, loaderContext: SassLoaderContext) => string);
-    implementation?: "sass-embedded" | "sass";
-    warnRuleAsWarning?: boolean;
-} & (Omit<StringOptions<"sync">, "charset" | "indentedSyntax"> | Omit<StringOptions$1<"sync">, "charset" | "indentedSyntax">);
-
-type StylusLoaderContext = {
-    environment: Environment;
-    resourcePath: string;
-    rootContext: string;
-};
-type StylusPlugin = string | ((renderer: unknown) => void);
-type StylusDefinition = [string, unknown] | [string, unknown, boolean];
-type StylusLoaderOptions = {
-    additionalData?: string | ((content: string, loaderContext: StylusLoaderContext) => Promise<string> | string);
-    disableCache?: boolean;
-    hoistAtrules?: boolean;
-    implementation?: string | ((code: string, options?: unknown) => unknown);
-    import?: string[];
-    include?: string[];
-    includeCSS?: boolean;
-    lineNumbers?: boolean;
-    define?: Record<string, unknown> | StylusDefinition[];
-    use?: StylusPlugin[];
-} & RenderOptions;
-
-interface Extracted {
-    css: string;
-    id: string;
-    map?: string;
-}
-interface Loader<T = Record<string, unknown>> {
-    alwaysProcess?: boolean;
-    name: string;
-    process: (this: LoaderContext<T>, payload: Payload) => Payload | Promise<Payload>;
-    test?: RegExp | ((file: string) => boolean);
-}
-interface LoaderContext<T = Record<string, unknown>> {
-    readonly alias?: Record<string, string>;
-    readonly assets: Map<string, Uint8Array>;
-    readonly autoModules: InternalStyleOptions["autoModules"];
-    readonly browserTargets: string[];
-    readonly cwd?: string;
-    readonly debug?: boolean;
-    readonly deps: Set<string>;
-    readonly dts: InternalStyleOptions["dts"];
-    readonly emit: InternalStyleOptions["emit"];
-    readonly environment: Environment;
-    readonly extensions: InternalStyleOptions["extensions"];
-    readonly extract: InternalStyleOptions["extract"];
-    readonly id: string;
-    readonly inject: InternalStyleOptions["inject"];
-    readonly inline: InternalStyleOptions["inline"];
-    readonly logger: RollupLogger;
-    readonly namedExports: InternalStyleOptions["namedExports"];
-    readonly options: T;
-    readonly plugin: PluginContext;
-    readonly sourceDir?: string;
-    readonly sourceMap: false | (SourceMapOptions & {
-        inline: boolean;
-    });
-    readonly useSourcemap: boolean;
-}
-interface Payload {
-    code: string;
-    dts?: string;
-    extracted?: Extracted;
-    map?: string;
-    meta?: CustomPluginOptions;
-}
-interface SourceMapOptions {
-    content?: boolean;
-    transform?: (map: RawSourceMap, name?: string) => void;
-}
-
-type MinifierContext = {
-    readonly browserTargets: string[];
-    readonly logger: RollupLogger;
-};
-interface Minifier<Options = Record<string, any>> {
-    handler: (this: MinifierContext, data: ExtractedData, sourceMap: LoaderContext["sourceMap"], options: Options) => Promise<ExtractedData>;
-    name: string;
-}
-
-type AutoModules = RegExp | boolean | ((id: string) => boolean);
-interface ExtractedData {
-    css: string;
-    map?: string;
-    name: string;
-}
-interface InjectOptions {
-    attributes?: Record<string, string>;
-    container?: string;
-    method?: string;
-    package?: string;
-    prepend?: boolean;
-    singleTag?: boolean;
-    treeshakeable?: boolean;
-}
-interface InternalStyleOptions extends StyleOptions {
-    emit: boolean;
-    extensions: NonNullable<StyleOptions["extensions"]>;
-    extract: boolean | string;
-    inject: InjectOptions | boolean | ((varname: string, id: string, output: string[]) => string);
-    inline: boolean;
-}
-type LightningCSSOptions = Omit<TransformOptions<CustomAtRules>, "code" | "cssModules" | "filename" | "minify" | "targets"> & {
-    modules?: TransformOptions<CustomAtRules>["cssModules"] & {
-        include?: AutoModules;
-    };
-};
-interface PostCSSConfigLoaderOptions {
-    ctx?: Record<string, unknown>;
-    path?: string;
-}
-interface PostCSSOptions {
-    config?: PostCSSConfigLoaderOptions | false;
-    import?: Partial<ImportOptions> | false;
-    modules?: ModulesOptions | boolean;
-    parser?: Config["parser"] | string;
-    plugins?: (AcceptedPlugin | string | [PluginCreator<unknown> | string, Record<string, unknown>] | [PluginCreator<unknown> | string] | null | undefined)[] | Record<string, unknown>;
-    stringifier?: Config["stringifier"] | string;
-    syntax?: Config["syntax"] | string;
-    to?: Config["to"];
-    url?: Partial<UrlOptions> | false;
-}
-interface StyleOptions {
-    alias?: Record<string, string>;
-    autoModules?: AutoModules;
-    cssnano?: Options;
-    dts?: boolean;
-    exclude?: ReadonlyArray<RegExp | string> | RegExp | string | undefined;
-    extensions?: string[];
-    include?: ReadonlyArray<RegExp | string> | RegExp | string | undefined;
-    less?: LESSLoaderOptions;
-    lightningcss?: LightningCSSOptions;
-    loaders?: Loader[];
-    minifier?: Minifier;
-    mode?: "emit" | "extract" | "inject" | "inline" | ["extract", string] | ["inject", InjectOptions | ((varname: string, id: string) => string)];
-    namedExports?: boolean | ((name: string) => string);
-    onExtract?: (data: ExtractedData) => boolean;
-    onImport?: (code: string, id: string) => void;
-    postcss?: PostCSSOptions;
-    sass?: SassLoaderOptions;
-    sourceMap?: boolean | "inline" | [boolean | "inline", SourceMapOptions] | [boolean | "inline"];
-    stylus?: StylusLoaderOptions;
-}
-
-export type { AutoModules as A, ExtractedData as E, InjectOptions as I, LightningCSSOptions as L, Minifier as M, PostCSSConfigLoaderOptions as P, StyleOptions as S, InternalStyleOptions as a, PostCSSOptions as b, Loader as c, LESSLoaderOptions as d, SassLoaderOptions as e, SassLoaderContext as f, StylusLoaderOptions as g, StylusDefinition as h, StylusLoaderContext as i, StylusPlugin as j, Extracted as k, LoaderContext as l };