esm-styles 0.2.3 → 0.2.5

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,20 +162,30 @@ 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 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) {
+            wrappedCss = `@layer ${layer} {\n${css}\n}`;
+            if (!uniqueLayers.includes(layer)) {
+                uniqueLayers.push(layer);
+            }
+        }
         await fs.writeFile(outputFile, wrappedCss, 'utf8');
-        cssFiles.push({ layer, file: `${layer}.css` });
+        floorFiles.push({ file: `${source}.css`, layer });
+        cssFiles.push({ floor: source, file: `${source}.css`, layer });
     }
     // 5. Create main CSS file
     const mainCssPath = path.join(outputPath, mainCssFile);
@@ -188,14 +199,13 @@ export async function build(configPath = 'esm-styles.config.js') {
         return `@import '${f.file}';`;
     })
         .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)
+    const floorImports = floorFiles.map((f) => `@import '${f.file}';`).join('\n');
+    const mainCss = [
+        uniqueLayers.length ? `@layer ${uniqueLayers.join(', ')};` : '',
+        floorImports,
+        varImports,
+    ]
         .filter(Boolean)
         .join('\n') + '\n';
     await fs.writeFile(mainCssPath, mainCss, 'utf8');

package/dist/lib/index.js

@@ -1,6 +1,6 @@
 import * as utils from './utils/index.js';
 import { toCssValue } from './utils/to-css-value.js';
-function flatWalk(obj, selectorPath = [], result = { rules: [], media: {}, layers: {} }, options = {}, currentMedia = []) {
+function flatWalk(obj, selectorPath = [], result = { rules: [], media: {}, layers: {}, containers: {} }, options = {}, currentMedia = [], currentContainers = []) {
     const props = {};
     for (const key in obj) {
         const value = obj[key];
@@ -16,7 +16,7 @@ function flatWalk(obj, selectorPath = [], result = { rules: [], media: {}, layer
         else if (typeof value === 'object' && value !== null) {
             if (key.startsWith('@media ')) {
                 // Recursively walk value, collecting rules for this media block
-                const nested = flatWalk(value, selectorPath, { rules: [], media: {}, layers: {} }, options, [...currentMedia, key]);
+                const nested = flatWalk(value, selectorPath, { rules: [], media: {}, layers: {}, containers: {} }, options, [...currentMedia, key], currentContainers);
                 const mediaKey = [...currentMedia, key].join(' && ');
                 if (!result.media[mediaKey])
                     result.media[mediaKey] = [];
@@ -27,11 +27,42 @@ function flatWalk(obj, selectorPath = [], result = { rules: [], media: {}, layer
                         result.media[nestedMediaKey] = [];
                     result.media[nestedMediaKey].push(...nested.media[nestedMediaKey]);
                 }
+                // Merge nested containers
+                for (const nestedContainerKey in nested.containers) {
+                    if (!result.containers[nestedContainerKey])
+                        result.containers[nestedContainerKey] = [];
+                    result.containers[nestedContainerKey].push(...nested.containers[nestedContainerKey]);
+                }
+            }
+            else if (key.startsWith('@container')) {
+                // Recursively walk value, collecting rules for this container block
+                const nested = flatWalk(value, selectorPath, { rules: [], media: {}, layers: {}, containers: {} }, options, currentMedia, [...currentContainers, key]);
+                const containerKey = [...currentContainers, key].join(' && ');
+                if (!result.containers[containerKey])
+                    result.containers[containerKey] = [];
+                result.containers[containerKey].push(...nested.rules);
+                // Also merge any nested containers
+                for (const nestedContainerKey in nested.containers) {
+                    if (!result.containers[nestedContainerKey])
+                        result.containers[nestedContainerKey] = [];
+                    result.containers[nestedContainerKey].push(...nested.containers[nestedContainerKey]);
+                }
+                // Merge nested media
+                for (const nestedMediaKey in nested.media) {
+                    if (!result.media[nestedMediaKey])
+                        result.media[nestedMediaKey] = [];
+                    result.media[nestedMediaKey].push(...nested.media[nestedMediaKey]);
+                }
             }
             else if (key.startsWith('@layer ')) {
                 if (!result.layers[key])
-                    result.layers[key] = { rules: [], media: {}, layers: {} };
-                flatWalk(value, selectorPath, result.layers[key], options, currentMedia);
+                    result.layers[key] = {
+                        rules: [],
+                        media: {},
+                        layers: {},
+                        containers: {},
+                    };
+                flatWalk(value, selectorPath, result.layers[key], options, currentMedia, currentContainers);
             }
             else if (key.startsWith('@')) {
                 // Other special keys (shorthands, etc.)
@@ -39,10 +70,7 @@ function flatWalk(obj, selectorPath = [], result = { rules: [], media: {}, layer
                 let handled = false;
                 if (options.mediaQueries && options.mediaQueries[shorthand]) {
                     const mediaKey = `@media ${options.mediaQueries[shorthand]}`;
-                    flatWalk(value, selectorPath, result, options, [
-                        ...currentMedia,
-                        mediaKey,
-                    ]);
+                    flatWalk(value, selectorPath, result, options, [...currentMedia, mediaKey], currentContainers);
                     handled = true;
                 }
                 if (options.selectorShorthands &&
@@ -50,20 +78,17 @@ function flatWalk(obj, selectorPath = [], result = { rules: [], media: {}, layer
                     const root = options.globalRootSelector || ':root';
                     for (const entry of options.selectorShorthands[shorthand]) {
                         if (entry.selector && !entry.mediaQuery) {
-                            flatWalk(value, [[root + entry.selector], ...selectorPath], result, options, currentMedia);
+                            flatWalk(value, [[root + entry.selector], ...selectorPath], result, options, currentMedia, currentContainers);
                             handled = true;
                         }
                         if (entry.selector && entry.mediaQuery) {
                             const mediaKey = `@media ${entry.mediaQuery}`;
-                            flatWalk(value, [[root + entry.selector], ...selectorPath], result, options, [...currentMedia, mediaKey]);
+                            flatWalk(value, [[root + entry.selector], ...selectorPath], result, options, [...currentMedia, mediaKey], currentContainers);
                             handled = true;
                         }
                         if (!entry.selector && entry.mediaQuery) {
                             const mediaKey = `@media ${entry.mediaQuery}`;
-                            flatWalk(value, selectorPath, result, options, [
-                                ...currentMedia,
-                                mediaKey,
-                            ]);
+                            flatWalk(value, selectorPath, result, options, [...currentMedia, mediaKey], currentContainers);
                             handled = true;
                         }
                     }
@@ -74,14 +99,14 @@ function flatWalk(obj, selectorPath = [], result = { rules: [], media: {}, layer
                     }
                     else {
                         const parts = key.split(',').map((k) => k.trim());
-                        flatWalk(value, [...selectorPath, parts], result, options, currentMedia);
+                        flatWalk(value, [...selectorPath, parts], result, options, currentMedia, currentContainers);
                     }
                 }
             }
             else {
                 // Always treat as selector segment if not a special key
                 const parts = key.split(',').map((k) => k.trim());
-                flatWalk(value, [...selectorPath, parts], result, options, currentMedia);
+                flatWalk(value, [...selectorPath, parts], result, options, currentMedia, currentContainers);
             }
         }
     }
@@ -184,6 +209,58 @@ function renderFlatMedia(media) {
     }
     return css;
 }
+function renderFlatContainers(containers) {
+    let css = '';
+    for (const key in containers) {
+        // If the key contains '&&', recursively nest the container blocks
+        const containerParts = key.split(' && ');
+        if (containerParts.length > 1) {
+            css += containerParts.reduceRight((inner, part) => `${part} {\n${inner}\n}`, renderFlatContainers({ ['']: containers[key] }));
+        }
+        else if (key === '') {
+            // Render rules directly, no block
+            // Group rules by their declarations (stringified)
+            const groups = {};
+            for (const rule of containers[key]) {
+                const declKey = JSON.stringify(rule.declarations);
+                if (!groups[declKey])
+                    groups[declKey] = [];
+                groups[declKey].push(rule.selector);
+            }
+            for (const declKey in groups) {
+                const selectors = groups[declKey].join(', ');
+                const declarations = JSON.parse(declKey);
+                css += `${selectors} {\n`;
+                for (const k in declarations) {
+                    css += `  ${k}: ${declarations[k]};\n`;
+                }
+                css += '}\n';
+            }
+        }
+        else {
+            css += `${key} {\n`;
+            // Group rules by their declarations (stringified)
+            const groups = {};
+            for (const rule of containers[key]) {
+                const declKey = JSON.stringify(rule.declarations);
+                if (!groups[declKey])
+                    groups[declKey] = [];
+                groups[declKey].push(rule.selector);
+            }
+            for (const declKey in groups) {
+                const selectors = groups[declKey].join(', ');
+                const declarations = JSON.parse(declKey);
+                css += `${selectors} {\n`;
+                for (const k in declarations) {
+                    css += `  ${k}: ${declarations[k]};\n`;
+                }
+                css += '}\n';
+            }
+            css += '}\n';
+        }
+    }
+    return css;
+}
 function mergeMedia(target, source) {
     for (const key in source) {
         if (!target[key])
@@ -192,7 +269,7 @@ function mergeMedia(target, source) {
     }
 }
 export function getCss(styles, options = {}) {
-    const result = flatWalk(styles, [], { rules: [], media: {}, layers: {} }, options);
+    const result = flatWalk(styles, [], { rules: [], media: {}, layers: {}, containers: {} }, options);
     if (typeof console !== 'undefined') {
         // console.log(
         //   '[esm-styles] flatWalk result:',
@@ -202,6 +279,7 @@ export function getCss(styles, options = {}) {
     let css = '';
     css += renderRules(result.rules);
     css += renderFlatMedia(result.media);
+    css += renderFlatContainers(result.containers);
     css += renderLayers(result.layers);
     return utils.prettifyCssString(css);
 }

package/doc/usage-guide.md

@@ -73,8 +73,14 @@ 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',

package/package.json

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