esm-styles 0.1.12 → 0.2.0

package/README.md

@@ -1,6 +1,15 @@
 # ESM Styles
 
-A TypeScript library for converting JavaScript objects to CSS strings, allowing for a cleaner syntax when writing CSS-in-JS.
+A CSS-in-JS solution for JavaScript/TypeScript projects.
+
+## Features
+
+- JavaScript to CSS conversion with an intuitive object syntax
+- 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
 
 ## Installation
 
@@ -10,146 +19,386 @@ npm install esm-styles
 
 ## Usage
 
-### Basic Usage
+### Basic Concept
 
-```javascript
-import { getCss } from 'esm-styles'
+ESM Styles lets you write CSS in JavaScript objects with a natural syntax that converts to proper CSS:
 
-const styles = {
-  body: {
-    margin: 0,
-    padding: 0,
-    fontFamily: 'sans-serif',
+```js
+// component.styles.mjs
+export default {
+  button: {
+    backgroundColor: '#4285f4',
+    color: 'white',
+    padding: '10px 20px',
+    borderRadius: '4px',
 
-    header: {
-      backgroundColor: '#333',
-      color: 'white',
-      padding: '1rem',
+    ':hover': {
+      backgroundColor: '#3367d6',
     },
 
-    'main, article': {
-      maxWidth: '800px',
-      margin: '0 auto',
-      padding: '1rem',
+    '@media (max-width: 768px)': {
+      padding: '8px 16px',
     },
+  },
+}
+```
+
+### CLI Usage
+
+Build your styles by creating a configuration file and running the CLI:
+
+```bash
+npx build
+```
+
+Or specify a custom config:
+
+```bash
+npx build path/to/config.js
+```
+
+Watch for changes:
+
+```bash
+npx watch
+```
+
+### Configuration
+
+Create a `esm-styles.config.js` in your project root (or use a custom path):
+
+```js
+export default {
+  basePath: './src/styles',
+  sourcePath: 'source',
+  outputPath: 'css',
+  sourceFilesSuffix: '.styles.mjs',
+
+  // Input layers
+  layers: ['defaults', 'components', 'layout'],
+
+  // Output
+  mainCssFile: 'styles.css',
+
+  // Global variables
+  globalVariables: 'global',
+  globalRootSelector: ':root',
+
+  // Media types and queries
+  media: {
+    theme: ['light', 'dark'],
+    device: ['mobile', 'tablet', 'desktop'],
+  },
 
-    footer: {
-      textAlign: 'center',
-      padding: '1rem',
-      backgroundColor: '#f5f5f5',
+  mediaSelectors: {
+    theme: {
+      light: [
+        {
+          selector: '.light',
+        },
+        {
+          selector: '.auto',
+          mediaQuery: 'screen and (prefers-color-scheme: light)',
+          prefix: 'auto',
+        },
+      ],
+      dark: [
+        {
+          selector: '.dark',
+        },
+        {
+          selector: '.auto',
+          mediaQuery: 'screen and (prefers-color-scheme: dark)',
+          prefix: 'auto',
+        },
+      ],
+    },
+    // Device selectors
+    device: {
+      mobile: [
+        {
+          mediaQuery: 'screen and (max-width: 767px)',
+        },
+      ],
+      tablet: [
+        {
+          mediaQuery: 'screen and (min-width: 768px) and (max-width: 1024px)',
+        },
+      ],
+      desktop: [
+        {
+          mediaQuery: 'screen and (min-width: 1025px)',
+        },
+      ],
     },
   },
+
+  // Media query shorthands
+  mediaQueries: {
+    mobile: '(max-width: 767px)',
+    tablet: '(min-width: 768px) and (max-width: 1024px)',
+    desktop: '(min-width: 1025px)',
+  },
 }
+```
+
+## JS to CSS Translation
+
+### Basic Selectors
 
-const css = getCss(styles)
-console.log(css)
+```js
+{
+  p: {
+    fontSize: '16px',
+    color: 'black',
+
+    a: {
+      color: 'blue'
+    },
+
+    strong: {
+      fontWeight: 'bold'
+    }
+  }
+}
 ```
 
-This will output CSS with nested selectors properly expanded:
+Compiles to:
 
 ```css
-body {
-  margin: 0;
-  padding: 0;
-  font-family: sans-serif;
+p {
+  font-size: 16px;
+  color: black;
+}
+
+p a {
+  color: blue;
 }
 
-body header {
-  background-color: #333;
-  color: white;
-  padding: 1rem;
+p strong {
+  font-weight: bold;
 }
+```
 
-body main,
-body article {
-  max-width: 800px;
-  margin: 0 auto;
-  padding: 1rem;
+### Class Selectors
+
+```js
+{
+  // Class selectors for non-HTML tag names
+  header: {
+    backgroundColor: '#f5f5f5',
+    padding: '20px'
+  },
+
+  // Class on HTML tag using underscore prefix
+  p: {
+    _highlight: {
+      backgroundColor: 'yellow'
+    }
+  }
 }
+```
 
-body footer {
-  text-align: center;
-  padding: 1rem;
+Compiles to:
+
+```css
+.header {
   background-color: #f5f5f5;
+  padding: 20px;
+}
+
+p.highlight {
+  background-color: yellow;
+}
+```
+
+### Double Underscore for Descendant Class Selector
+
+```js
+{
+  modal: {
+    position: 'relative',
+
+    __close: {
+      position: 'absolute',
+      top: '10px',
+      right: '10px'
+    }
+  }
 }
 ```
 
-### Advanced Features
+Compiles to:
 
-#### Media Queries
+```css
+.modal {
+  position: relative;
+}
 
-```javascript
-import { getCss } from 'esm-styles'
+.modal .close {
+  position: absolute;
+  top: 10px;
+  right: 10px;
+}
+```
 
-const styles = {
-  body: {
-    fontSize: '16px',
+### Multiple Selectors
 
-    '@media (max-width: 768px)': {
-      fontSize: '14px',
-    },
+```js
+{
+  'button, .btn': {
+    padding: '10px 20px'
   },
+
+  'input[type="text"], input[type="email"]': {
+    borderRadius: '4px'
+  }
 }
+```
+
+### Nested Media Queries
 
-const css = getCss(styles)
+```js
+{
+  card: {
+    display: 'flex',
+
+    '@media (max-width: 768px)': {
+      flexDirection: 'column',
+
+      '@media (orientation: portrait)': {
+        padding: '10px'
+      }
+    }
+  }
+}
 ```
 
-#### Named Media Queries
+### Named Media Queries
 
-```javascript
-import { getCss } from 'esm-styles'
+```js
+{
+  main: {
+    display: 'grid',
 
-const styles = {
-  container: {
-    width: '1200px',
-    '@tablet': {
-      width: '100%',
-      padding: '0 20px',
-    },
     '@mobile': {
-      padding: '0 10px',
+      display: 'flex',
+      flexDirection: 'column'
     },
-  },
+
+    '@desktop': {
+      gridTemplateColumns: 'repeat(3, 1fr)'
+    }
+  }
 }
+```
+
+### Theme Support
+
+```js
+{
+  card: {
+    backgroundColor: 'white',
+    color: 'black',
 
-const mediaQueries = {
-  tablet: '(max-width: 1024px)',
-  mobile: '(max-width: 480px)',
+    '@dark': {
+      backgroundColor: '#222',
+      color: 'white'
+    }
+  }
 }
+```
+
+### CSS Variables
+
+Define variables in a global variables file:
 
-const css = getCss(styles, mediaQueries)
+```js
+// global.styles.mjs
+export default {
+  colors: {
+    primary: '#4285f4',
+    secondary: '#34a853',
+    error: '#ea4335',
+  },
+  spacing: {
+    sm: '8px',
+    md: '16px',
+    lg: '24px',
+  },
+}
 ```
 
-#### Class and Tag Selectors
+Define theme-specific variables:
 
-```javascript
-import { getCss } from 'esm-styles'
+```js
+// light.styles.mjs
+export default {
+  paper: {
+    bright: '#ffffff',
+    tinted: '#f0f0f0',
+  },
+  ink: {
+    bright: '#000000',
+    faded: '#333333',
+    accent: '#ff0000',
+  },
+}
+```
 
-const styles = {
-  // Tag selector (div)
-  div: {
-    margin: '10px',
+```js
+// dark.styles.mjs
+export default {
+  paper: {
+    bright: '#000000',
+    tinted: '#323232',
+  },
+  ink: {
+    bright: '#ffffff',
+    faded: '#b3b3b3',
+  },
+}
+```
 
-    // Nested tag selector (p inside div)
-    p: {
-      lineHeight: 1.5,
-    },
+Use with supporting modules:
 
-    // Class selector (with underscore prefix)
-    _highlight: {
-      backgroundColor: 'yellow',
-    },
+```js
+// component.styles.mjs
+import $theme from './$theme.mjs'
 
-    // Descendant class selector (with double underscore)
-    __text: {
-      color: 'blue',
-    },
+export default {
+  button: {
+    backgroundColor: $theme.paper.bright,
+    color: $theme.ink.bright,
+    padding: '10px 20px',
   },
 }
+```
+
+## Advanced Features
 
-const css = getCss(styles)
+### Layering
+
+Organize your styles in layers for better control over specificity:
+
+```js
+// defaults.styles.mjs, components.styles.mjs, layout.styles.mjs
 ```
 
+The build process wraps each in an appropriate layer and generates a main CSS file with proper import order.
+
+### CSS Variable Inheritance
+
+Missing variables in one theme automatically inherit from the previous theme in the configuration.
+
+## Additional documentation
+
+For humans: [doc/usage-guide.md](doc/usage-guide.md)
+
+For AI assistants: [doc/ai-guide.md](doc/ai-guide.md)
+
+API reference: [doc/api-reference.md](doc/api-reference.md)
+
 ## License
 
 MIT

package/dist/lib/build.js

@@ -4,7 +4,6 @@ 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 ---
@@ -86,8 +85,8 @@ export async function build(configPath = 'esm-styles.config.js') {
             }
             // --- Supporting module generation ---
             // Debug: log mergedSets and sets
-            console.log('[DEBUG] sets:', sets);
-            console.log('[DEBUG] mergedSets:', inspect(mergedSets, { depth: 10 }));
+            // console.log('[DEBUG] sets:', sets)
+            // console.log('[DEBUG] mergedSets:', inspect(mergedSets, { depth: 10 }))
             // Define the recursive function here so it has access to sets and mergedSets
             const buildSupportingModule = (path, isRoot) => {
                 const allKeys = new Set();
@@ -101,11 +100,24 @@ export async function build(configPath = 'esm-styles.config.js') {
                     }
                 }
                 // Debug: show allKeys and values at this path
-                console.log('[DEBUG] path:', path.join('.'), 'allKeys:', Array.from(allKeys));
-                for (const set of sets) {
-                    const v = path.length === 0 ? mergedSets[set] : _.get(mergedSets[set], path);
-                    console.log('[DEBUG] set:', set, 'path:', path.join('.'), 'value:', JSON.stringify(v));
-                }
+                // console.log(
+                //   '[DEBUG] path:',
+                //   path.join('.'),
+                //   'allKeys:',
+                //   Array.from(allKeys)
+                // )
+                // for (const set of sets) {
+                //   const v =
+                //     path.length === 0 ? mergedSets[set] : _.get(mergedSets[set], path)
+                // console.log(
+                //   '[DEBUG] set:',
+                //   set,
+                //   'path:',
+                //   path.join('.'),
+                //   'value:',
+                //   JSON.stringify(v)
+                // )
+                // }
                 const result = {};
                 for (const key of allKeys) {
                     if (key === '') {
@@ -132,7 +144,12 @@ export async function build(configPath = 'esm-styles.config.js') {
                     }
                 }
                 // Debug log for each recursion
-                console.log('[DEBUG] path:', path.join('.'), 'result:', JSON.stringify(result, null, 2));
+                // console.log(
+                //   '[DEBUG] path:',
+                //   path.join('.'),
+                //   'result:',
+                //   JSON.stringify(result, null, 2)
+                // )
                 return result;
             };
             const supportingModuleObj = buildSupportingModule([], true);

package/dist/lib/utils/content.js

@@ -1,13 +1,17 @@
-export const contentValue = value => {
+export const contentValue = (value) => {
     if (typeof value !== 'string')
         return value;
     // If already quoted, return as is
     if (/^'.*'$/.test(value) || /^".*"$/.test(value))
         return value;
-    // Convert each character to CSS unicode escape: \00xxxx
+    // If all characters are printable ASCII, return as quoted string
+    if (/^[\x20-\x7E]*$/.test(value)) {
+        return `'${value}'`;
+    }
+    // Otherwise, convert each character to CSS unicode escape: \00xxxx
     const unicode = value
         .split('')
-        .map(ch => {
+        .map((ch) => {
         const code = ch.codePointAt(0);
         if (!code)
             return '';