esm-styles 0.2.4 → 0.2.6

package/README.md

@@ -8,8 +8,7 @@ A CSS-in-JS solution for JavaScript/TypeScript projects.
 - Build CSS from organized source files with a simple CLI
 - CSS layering support for proper style encapsulation
 - Media query and device/theme selectors with shorthands
-- CSS variables with inheritance between themes
-- Supporting modules for easy CSS variable usage
+- CSS variable sets for different themes and devices
 
 ## Installation
 
@@ -21,28 +20,63 @@ npm install esm-styles
 
 ### Basic Concept
 
-ESM Styles lets you write CSS in JavaScript objects with a natural syntax that converts to proper CSS:
+ESM Styles lets you write and store styles in JavaScript this way:
 
 ```js
-// component.styles.mjs
+// article.styles.mjs
+import $device from './$device.mjs'
+import $theme from './$theme.mjs'
+import { card } from './card.styles.mjs'
+
 export default {
-  button: {
-    backgroundColor: '#4285f4',
-    color: 'white',
-    padding: '10px 20px',
-    borderRadius: '4px',
+  article: {
+    display: 'flex',
+
+    card,
 
-    ':hover': {
-      backgroundColor: '#3367d6',
+    '@max-tablet': {
+      flexDirection: 'column',
     },
 
-    '@media (max-width: 768px)': {
-      padding: '8px 16px',
+    button: {
+      borderRadius: $device.radii.md,
+      backgroundColor: $theme.paper.tinted,
+
+      '@dark': {
+        fontWeight: 300,
+      },
     },
   },
 }
 ```
 
+### Sample Directory Structure
+
+```
+monorepo/
+├── package.json
+└── packages/
+  ├── app/
+  │ ├── package.json
+  │ └── src/
+  │   ├── css/
+  │   ├── styles.css
+  │   └── components/
+  │     ├── article.tsx
+  │     ├── button.tsx
+  │     └── card.tsx
+  └── styles/
+    ├── $device.mjs
+    ├── $theme.mjs
+    ├── components/
+    │ ├── article.styles.mjs
+    │ ├── button.styles.mjs
+    │ └── card.styles.mjs
+    ├── components.styles.mjs
+    ├── esm-styles.config.js
+    └── package.json
+```
+
 ### CLI Usage
 
 Build your styles by creating a configuration file and running the CLI:

package/dist/lib/build.js

@@ -4,6 +4,7 @@ import { getMediaShorthands } from './utils/media-shorthand.js';
 import { isEndValue } from './utils/index.js';
 import path from 'node:path';
 import fs from 'node:fs/promises';
+// import { inspect } from 'node:util'
 import _ from 'lodash';
 export async function build(configPath = 'esm-styles.config.js') {
     // --- Supporting module generation ---
@@ -19,7 +20,7 @@ export async function build(configPath = 'esm-styles.config.js') {
     const sourcePath = path.join(basePath, config.sourcePath || '');
     const outputPath = path.join(basePath, config.outputPath || '');
     const suffix = config.sourceFilesSuffix || '.styles.mjs';
-    const layers = config.layers || [];
+    const floors = config.floors || [];
     const mainCssFile = config.mainCssFile || 'styles.css';
     // Merge media shorthands
     const mediaShorthands = getMediaShorthands(config);
@@ -161,41 +162,64 @@ export async function build(configPath = 'esm-styles.config.js') {
             await fs.writeFile(supportingModulePath, moduleContent, 'utf8');
         }
     }
-    // 4. Process each layer (legacy, keep for now)
-    for (const layer of layers) {
-        const inputFile = path.join(sourcePath, `${layer}${suffix}`);
-        const outputFile = path.join(outputPath, `${layer}.css`);
+    // 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 = [];
+    for (const floor of floors) {
+        const { source, layer } = floor;
+        const inputFile = path.join(sourcePath, `${source}${suffix}`);
+        const outputFile = path.join(outputPath, `${source}.css`);
         const fileUrl = pathToFileUrl(inputFile).href + `?update=${Date.now()}`;
         const stylesObj = (await import(fileUrl)).default;
-        // Always call getCss for the layer object, so media queries are rendered
         const css = getCss(stylesObj, {
             ...mediaShorthands,
             globalRootSelector: config.globalRootSelector,
         });
-        const wrappedCss = `@layer ${layer} {\n${css}\n}`;
+        let wrappedCss = css;
+        if (layer) {
+            // add layer to order in any case, even if the floor is not imported
+            if (!uniqueLayers.includes(layer)) {
+                uniqueLayers.push(layer);
+            }
+            wrappedCss = `@layer ${layer} {\n${css}\n}`;
+        }
         await fs.writeFile(outputFile, wrappedCss, 'utf8');
-        cssFiles.push({ layer, file: `${layer}.css` });
+        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 layers
-    const layerFiles = cssFiles.filter((f) => f.layer).map((f) => f.file);
-    const layerNames = cssFiles
-        .filter((f) => f.layer)
-        .map((f) => f.layer)
-        .join(', ');
-    const layerImports = layerFiles.map((f) => `@import '${f}';`).join('\n');
-    const mainCss = [layerNames ? `@layer ${layerNames};` : '', layerImports, varImports]
+    // 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 mainCss = [
+        uniqueLayers.length ? `@layer ${uniqueLayers.join(', ')};` : '',
+        floorImports,
+        varImports,
+    ]
         .filter(Boolean)
         .join('\n') + '\n';
     await fs.writeFile(mainCssPath, mainCss, 'utf8');

package/doc/usage-guide.md

@@ -73,12 +73,21 @@ export default {
   outputPath: 'css',
   sourceFilesSuffix: '.styles.mjs',
 
-  // Input layers - order matters
-  layers: ['defaults', 'components', 'layout'],
+  // Input files and their layers (order of layers matters)
+  floors: [
+    { source: 'defaults', layer: 'defaults' }, // wrap in layer 'defaults'
+    { source: 'components', layer: 'components' }, // wrap in layer 'components'
+    { source: 'layout', layer: 'layout' }, // wrap in layer 'layout'
+    { source: 'basic' }, // stay out of any layer
+    { source: 'more-layout', layer: 'layout' }, // wrap in layer 'layout'
+  ],
 
   // 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.4",
+  "version": "0.2.6",
   "description": "A library for working with ESM styles",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",