esm-styles 0.3.0 → 0.3.2

package/README.md

@@ -108,8 +108,15 @@ export default {
   outputPath: 'css',
   sourceFilesSuffix: '.styles.mjs',
 
-  // Input layers
-  layers: ['defaults', 'components', 'layout'],
+  // Input floors (replaces layers)
+  floors: [
+    { source: 'defaults', layer: 'defaults' },
+    { source: 'components', layer: 'components' },
+    { source: 'layout', layer: 'layout' },
+  ],
+
+  // Specify which floors to include in main CSS
+  importFloors: ['defaults', 'components', 'layout'],
 
   // Output
   mainCssFile: 'styles.css',
@@ -417,15 +424,28 @@ export default {
 
 ## Advanced Features
 
-### Layering
+### Layering with Floors
 
-Organize your styles in layers for better control over specificity:
+Organize your styles in floors for better control over specificity and output:
 
 ```js
-// defaults.styles.mjs, components.styles.mjs, layout.styles.mjs
+// Configuration example
+floors: [
+  { source: 'defaults', layer: 'defaults' },
+  { source: 'components', layer: 'components' },
+  { source: 'layout', layer: 'layout' },
+  { source: 'utilities' }, // No layer wrapper
+  { source: 'overrides', outputPath: 'special' }, // Custom output path
+]
 ```
 
-The build process wraps each in an appropriate layer and generates a main CSS file with proper import order.
+Each floor can:
+
+- Be wrapped in a CSS layer (optional)
+- Have a custom output path (optional)
+- Be included or excluded from the main CSS file via `importFloors`
+
+The build process wraps floors in their respective layers and generates a main CSS file with proper import order.
 
 ### CSS Variable Inheritance
 

package/doc/ai-guide.md

@@ -31,7 +31,7 @@ button {
   p: { fontSize: '16px' },       // -> p { font-size: 16px; }
 
   // Non-HTML tags become class selectors
-  header: { display: 'flex' },   // -> .header { display: flex; }
+  heading: { display: 'flex' },   // -> .heading { display: flex; }
   card: { padding: '20px' }      // -> .card { padding: 20px; }
 }
 ```
@@ -91,6 +91,28 @@ button {
 }
 ```
 
+### ⚠️ CRITICAL: Ampersand (&) Syntax is NOT Supported
+
+```js
+// ❌ WRONG: These will NOT work (common mistake from SCSS/Sass)
+{
+  button: {
+    '&:hover': { opacity: 0.9 },     // ❌ Ampersand not supported
+    '&.active': { color: 'red' },     // ❌ Will not work
+    '&[disabled]': { opacity: 0.5 }  // ❌ Will not work
+  }
+}
+
+// ✅ CORRECT: Use direct selectors instead
+{
+  button: {
+    ':hover': { opacity: 0.9 },      // ✅ Direct pseudo-class
+    active: { color: 'red' },         // ✅ Class name (if not HTML tag)
+    '[disabled]': { opacity: 0.5 }   // ✅ Direct attribute selector
+  }
+}
+```
+
 ### Multiple Selectors
 
 ```js
@@ -150,6 +172,8 @@ export default {
     // Use variable references - gets converted to var(--color-primary)
     backgroundColor: $theme.color.primary,
     color: $theme.color.textOnPrimary,
+    // in case of concatenation, use .var property, otherwise it will be [object Object]
+    border: `1px solid ${$theme.color.primary.var}`,
   },
 }
 ```
@@ -184,7 +208,12 @@ export default {
   basePath: './src/styles',
   sourcePath: 'source',
   outputPath: 'css',
-  layers: ['base', 'components', 'utilities'],
+  floors: [
+    { source: 'base', layer: 'base' },
+    { source: 'components', layer: 'components' },
+    { source: 'utilities', layer: 'utilities' },
+  ],
+  importFloors: ['base', 'components', 'utilities'],
   mainCssFile: 'styles.css',
 
   // Media shorthand definitions

package/doc/api-reference.md

@@ -120,6 +120,12 @@ Represents a set of CSS property declarations.
 The `esm-styles.config.js` file exports a configuration object with the following structure:
 
 ```typescript
+interface FloorConfig {
+  source: string
+  layer?: string
+  outputPath?: string
+}
+
 interface ESMStylesConfig {
   // Paths
   basePath: string
@@ -128,7 +134,8 @@ interface ESMStylesConfig {
   sourceFilesSuffix?: string
 
   // Input
-  layers: string[]
+  floors: FloorConfig[]
+  importFloors?: string[]
 
   // Output
   mainCssFile: string
@@ -146,19 +153,28 @@ interface ESMStylesConfig {
 
 #### Properties
 
-| Property             | Type     | Description                   | Default       |
-| -------------------- | -------- | ----------------------------- | ------------- |
-| `basePath`           | string   | Base directory for styles     | -             |
-| `sourcePath`         | string   | Source files directory        | -             |
-| `outputPath`         | string   | Output CSS directory          | -             |
-| `sourceFilesSuffix`  | string   | Suffix for source files       | '.styles.mjs' |
-| `layers`             | string[] | Array of layer names          | -             |
-| `mainCssFile`        | string   | Output CSS file name          | -             |
-| `globalVariables`    | string   | Global variables file name    | -             |
-| `globalRootSelector` | string   | Root selector for variables   | ':root'       |
-| `media`              | object   | Media types and variables     | -             |
-| `mediaSelectors`     | object   | Media selector configurations | -             |
-| `mediaQueries`       | object   | Named media query shorthands  | -             |
+| Property             | Type          | Description                        | Default       |
+| -------------------- | ------------- | ---------------------------------- | ------------- |
+| `basePath`           | string        | Base directory for styles          | -             |
+| `sourcePath`         | string        | Source files directory             | -             |
+| `outputPath`         | string        | Output CSS directory               | -             |
+| `sourceFilesSuffix`  | string        | Suffix for source files            | '.styles.mjs' |
+| `floors`             | FloorConfig[] | Array of floor configurations      | -             |
+| `importFloors`       | string[]      | Floor names to include in main CSS | -             |
+| `mainCssFile`        | string        | Output CSS file name               | -             |
+| `globalVariables`    | string        | Global variables file name         | -             |
+| `globalRootSelector` | string        | Root selector for variables        | ':root'       |
+| `media`              | object        | Media types and variables          | -             |
+| `mediaSelectors`     | object        | Media selector configurations      | -             |
+| `mediaQueries`       | object        | Named media query shorthands       | -             |
+
+#### FloorConfig Properties
+
+| Property     | Type   | Description                                  | Default |
+| ------------ | ------ | -------------------------------------------- | ------- |
+| `source`     | string | Source file name (without suffix)            | -       |
+| `layer`      | string | CSS layer name to wrap the floor styles in   | -       |
+| `outputPath` | string | Custom output path for this floor's CSS file | -       |
 
 ### Media Selectors