esm-styles 0.2.5 → 0.2.7

package/dist/lib/build.js

@@ -22,6 +22,12 @@ export async function build(configPath = 'esm-styles.config.js') {
     const suffix = config.sourceFilesSuffix || '.styles.mjs';
     const floors = config.floors || [];
     const mainCssFile = config.mainCssFile || 'styles.css';
+    // Helper function to generate CSS comment header
+    const generateCssComment = (sourceName) => {
+        const normalizedBasePath = (config.basePath || '.').replace(/^\.\//, '');
+        const sourceFilePath = path.join(normalizedBasePath, config.sourcePath || '', `${sourceName}${suffix}`);
+        return `/* This CSS was automatically generated from ${sourceFilePath}, do not edit directly */\n`;
+    };
     // Merge media shorthands
     const mediaShorthands = getMediaShorthands(config);
     // Ensure output directory exists
@@ -35,7 +41,8 @@ export async function build(configPath = 'esm-styles.config.js') {
         const varsObj = (await import(fileUrl)).default;
         const cssVars = getCssVariables(varsObj);
         const rootSelector = config.globalRootSelector || ':root';
-        const wrappedCss = `${rootSelector} {\n${cssVars}\n}`;
+        const comment = generateCssComment(config.globalVariables);
+        const wrappedCss = `${comment}${rootSelector} {\n${cssVars}\n}`;
         await fs.writeFile(outputFile, wrappedCss, 'utf8');
         cssFiles.push({ type: 'global', file: 'global.css' });
     }
@@ -73,7 +80,8 @@ export async function build(configPath = 'esm-styles.config.js') {
                             fullSelector = `${rootSelector} ${selector}`;
                         }
                     }
-                    const block = `${fullSelector} {\n${cssVars}\n}`;
+                    const comment = generateCssComment(setName);
+                    const block = `${comment}${fullSelector} {\n${cssVars}\n}`;
                     await fs.writeFile(outputFile, block, 'utf8');
                     cssFiles.push({
                         type: 'media',
@@ -163,6 +171,8 @@ export async function build(configPath = 'esm-styles.config.js') {
         }
     }
     // 4. Process each floor (replaces legacy layers)
+    const importFloors = config.importFloors || floors.map((f) => f.source);
+    // Track unique layer names in order of first appearance (for imported floors only)
     const uniqueLayers = [];
     // Track output files for each floor
     const floorFiles = [];
@@ -176,38 +186,55 @@ export async function build(configPath = 'esm-styles.config.js') {
             ...mediaShorthands,
             globalRootSelector: config.globalRootSelector,
         });
-        let wrappedCss = css;
+        const comment = generateCssComment(source);
+        let wrappedCss = `${comment}${css}`;
         if (layer) {
-            wrappedCss = `@layer ${layer} {\n${css}\n}`;
+            // add layer to order in any case, even if the floor is not imported
             if (!uniqueLayers.includes(layer)) {
                 uniqueLayers.push(layer);
             }
+            wrappedCss = `${comment}@layer ${layer} {\n${css}\n}`;
         }
         await fs.writeFile(outputFile, wrappedCss, 'utf8');
-        floorFiles.push({ file: `${source}.css`, layer });
+        floorFiles.push({ file: `${source}.css`, layer, source });
         cssFiles.push({ floor: source, file: `${source}.css`, layer });
     }
     // 5. Create main CSS file
     const mainCssPath = path.join(outputPath, mainCssFile);
+    // Type guard for cssFiles entries with type 'global' or 'media'
+    function isGlobalOrMedia(f) {
+        return ((f.type === 'global' || f.type === 'media') && typeof f.file === 'string');
+    }
     // Compose imports for variable sets
-    const varImports = cssFiles
-        .filter((f) => f.type === 'global' || f.type === 'media')
-        .map((f) => {
+    function toImportStatement(f) {
         if (f.mediaQuery) {
             return `@import '${f.file}' ${f.mediaQuery};`;
         }
         return `@import '${f.file}';`;
-    })
+    }
+    const varImports = cssFiles.filter(isGlobalOrMedia)
+        .map(toImportStatement)
         .join('\n');
-    // Compose imports for floors (in order)
-    const floorImports = floorFiles.map((f) => `@import '${f.file}';`).join('\n');
-    const mainCss = [
-        uniqueLayers.length ? `@layer ${uniqueLayers.join(', ')};` : '',
-        floorImports,
-        varImports,
-    ]
-        .filter(Boolean)
-        .join('\n') + '\n';
+    // Compose imports for floors (in order, only those in importFloors)
+    function isImportedFloor(f) {
+        return importFloors.includes(f.source);
+    }
+    function importStatement(f) {
+        return `@import '${f.file}';`;
+    }
+    const importedFloorFiles = floorFiles.filter(isImportedFloor);
+    const floorImports = importedFloorFiles.map(importStatement).join('\n');
+    const normalizedBasePath = (config.basePath || '.').replace(/^\.\//, '');
+    const mainCssComment = `/* This CSS was automatically generated as the main styles file from ${normalizedBasePath}, do not edit directly */\n`;
+    const mainCss = mainCssComment +
+        [
+            uniqueLayers.length ? `@layer ${uniqueLayers.join(', ')};` : '',
+            floorImports,
+            varImports,
+        ]
+            .filter(Boolean)
+            .join('\n') +
+        '\n';
     await fs.writeFile(mainCssPath, mainCss, 'utf8');
 }
 // Helper for file URL import

package/doc/usage-guide.md

@@ -85,6 +85,9 @@ export default {
   // Output
   mainCssFile: 'styles.css',
 
+  // floors to include in the main CSS file
+  importFloors: ['defaults', 'components', 'layout'],
+
   // CSS Variables configuration
   globalVariables: 'global',
   globalRootSelector: ':root',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "esm-styles",
-  "version": "0.2.5",
+  "version": "0.2.7",
   "description": "A library for working with ESM styles",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",