esm-styles 0.2.8 → 0.3.1

package/doc/usage-guide.md

@@ -73,13 +73,14 @@ export default {
   outputPath: 'css',
   sourceFilesSuffix: '.styles.mjs',
 
-  // Input files and their layers (order of layers matters)
+  // Input floors (replaces layers parameter)
   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'
+    { source: 'special', outputPath: 'alt' }, // output to custom path
   ],
 
   // Output
@@ -149,7 +150,8 @@ export default {
 | `sourcePath`         | Directory inside `basePath` containing source style files                 |
 | `outputPath`         | Directory inside `basePath` where output CSS files will be written        |
 | `sourceFilesSuffix`  | Suffix for source style files (default: `.styles.mjs`)                    |
-| `layers`             | Array of layer names, defining the order of CSS specificity               |
+| `floors`             | Array of floor configurations, defining sources, layers, and output paths |
+| `importFloors`       | Array of floor names to include in the main CSS file                      |
 | `mainCssFile`        | Name of the output CSS file that imports all layer and variable files     |
 | `globalVariables`    | Name of the file containing global CSS variables                          |
 | `globalRootSelector` | Root selector for CSS variables (default: `:root`)                        |
@@ -316,9 +318,13 @@ Use commas to target multiple selectors:
 }
 ```
 
-## Layers
+## Floors and Layers
 
-ESM Styles supports @layer directives:
+ESM Styles supports @layer directives through its floors configuration system.
+
+### Inline Layers
+
+You can still use inline @layer directives in your styles:
 
 ```js
 {
@@ -333,43 +339,88 @@ ESM Styles supports @layer directives:
 }
 ```
 
-Your configuration can define multiple layer files that will be automatically wrapped in their respective layer directives:
+### Floors Configuration
+
+The floors system replaces the old layers configuration and provides more flexibility:
+
+```js
+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
+]
+```
+
+Each floor can:
+
+- **source**: Name of the source file (required)
+- **layer**: CSS layer name to wrap the styles in (optional)
+- **outputPath**: Custom output directory for this floor's CSS (optional)
+
+### Floor Examples
 
 ```js
 // defaults.styles.mjs
 export default {
-  // Base styles
+  // Base styles - will be wrapped in @layer defaults
 }
 
 // components.styles.mjs
 export default {
-  // Component styles
+  // Component styles - will be wrapped in @layer components
 }
 
-// layout.styles.mjs
+// utilities.styles.mjs
 export default {
-  // Layout styles
+  // Utility styles - no layer wrapper
 }
 ```
 
-The build process generates:
+### Build Output
+
+The build process generates CSS files based on your floors configuration:
 
 ```css
+/* styles.css (main file) */
 @layer defaults, components, layout;
 
+@import url('./defaults.css');
+@import url('./components.css');
+@import url('./layout.css');
+@import url('./utilities.css'); /* no layer */
+
+/* Files with custom outputPath go to their specified directories */
+```
+
+Each layered CSS file has its content wrapped in the appropriate layer:
+
+```css
+/* defaults.css */
 @layer defaults {
-  /* defaults.css content */
+  /* defaults styles content */
 }
 
+/* components.css */
 @layer components {
-  /* components.css content */
+  /* components styles content */
 }
 
-@layer layout {
-  /* layout.css content */
-}
+/* utilities.css (no layer) */
+/* utilities styles content directly, no layer wrapper */
 ```
 
+### Import Control
+
+Use `importFloors` to control which floors are included in the main CSS file:
+
+```js
+importFloors: ['defaults', 'components', 'layout'], // utilities excluded from main CSS
+```
+
+This allows you to generate standalone CSS files that can be imported separately or conditionally.
+
 ## Media Queries
 
 ### Standard Media Queries

package/package.json

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

package/dist/lib/getCss.d.ts

@@ -1,14 +0,0 @@
-/**
- * Main function for converting JavaScript objects to CSS
- */
-import { CssStyles, MediaQueries, MediaPrefixes, AutoConfig } from './types/index.js';
-/**
- * Converts a JavaScript style object to CSS string
- * @param object - The JavaScript object to convert to CSS
- * @param mediaQueries - Media query definitions (e.g., { 'phone': '(max-width: 499px)' })
- * @param mediaPrefixes - Media prefix definitions (e.g., { 'dark': ':root.dark' })
- * @param auto - Auto mode configuration (e.g., { 'dark': [':root.auto', 'screen and (prefers-color-scheme: dark)'] })
- * @returns CSS string
- */
-export declare function getCss(object: CssStyles, mediaQueries?: MediaQueries, mediaPrefixes?: MediaPrefixes, auto?: AutoConfig): string;
-export default getCss;

package/dist/lib/getCss.js

@@ -1,260 +0,0 @@
-/**
- * Main function for converting JavaScript objects to CSS
- */
-import { traverseObject, determineNodeType } from './utils/traversal.js';
-import { indent } from './utils/common.js';
-import { obj2css, prettifyCss } from './utils/obj2css.js';
-import { joinSelectors, cartesianSelectors } from './utils/selectors.js';
-import { formatContentValue } from './utils/content.js';
-import { jsKeyToCssKey } from './utils/common.js';
-import { processMediaQueries } from './utils/media.js';
-/**
- * Converts a JavaScript style object to CSS string
- * @param object - The JavaScript object to convert to CSS
- * @param mediaQueries - Media query definitions (e.g., { 'phone': '(max-width: 499px)' })
- * @param mediaPrefixes - Media prefix definitions (e.g., { 'dark': ':root.dark' })
- * @param auto - Auto mode configuration (e.g., { 'dark': [':root.auto', 'screen and (prefers-color-scheme: dark)'] })
- * @returns CSS string
- */
-export function getCss(object, mediaQueries = {}, mediaPrefixes = {}, auto) {
-    // Initialize various objects to collect different types of CSS rules
-    let cssStyle = {};
-    const layerStatements = [];
-    let layerObject = {};
-    let containerObject = {};
-    const mediaObject = {};
-    let prefixObject = {};
-    // Process the object by traversing it and handling different node types
-    traverseObject(object, (node, path, _, __) => {
-        if (!path)
-            return node;
-        const nodeType = determineNodeType(node, path);
-        const pathParts = path.split('\\');
-        const key = pathParts.pop() || '';
-        // Skip processing media query nodes that are nested within selectors
-        // as they will be handled separately in the media query section
-        const isNestedMediaQuery = pathParts.some((part) => part.startsWith('@media ') ||
-            (part.startsWith('@') &&
-                mediaQueries[part.replace(/^@\s*/, '')] !== undefined));
-        switch (nodeType) {
-            case 'selector': {
-                // Skip if this is inside a media query - it will be handled separately
-                if (isNestedMediaQuery) {
-                    break;
-                }
-                // Handle CSS property-value pairs
-                const selector = joinSelectors(pathParts);
-                // Create cartesian product of selectors for comma-separated parts
-                if (pathParts.some((part) => part.includes(','))) {
-                    const classPaths = pathParts.map((part) => part.split(',').map((p) => p.trim()));
-                    const allPaths = cartesianSelectors(classPaths);
-                    // Apply the property-value to each selector
-                    allPaths.forEach((selectorPath) => {
-                        const cssKey = jsKeyToCssKey(key);
-                        let value = node;
-                        // Special handling for content property
-                        if (cssKey === 'content') {
-                            value = formatContentValue(value);
-                        }
-                        // Create the CSS object and merge it
-                        const cssObject = {
-                            [selectorPath]: { [cssKey]: value },
-                        };
-                        cssStyle = mergeDeep(cssStyle, cssObject);
-                    });
-                }
-                else {
-                    // Simple case - no commas in selectors
-                    const cssKey = jsKeyToCssKey(key);
-                    let value = node;
-                    // Special handling for content property
-                    if (cssKey === 'content') {
-                        value = formatContentValue(value);
-                    }
-                    // Create the CSS object and merge it
-                    const cssObject = {
-                        [selector]: { [cssKey]: value },
-                    };
-                    cssStyle = mergeDeep(cssStyle, cssObject);
-                }
-                break;
-            }
-            case 'layer statement': {
-                // Handle @layer statements
-                const statement = `${key}${node ? ' ' + node : ''};`;
-                if (!layerStatements.includes(statement)) {
-                    layerStatements.push(statement);
-                }
-                break;
-            }
-            case 'layer block': {
-                // Handle @layer blocks
-                const selector = joinSelectors(pathParts);
-                const object = { [key]: { [selector]: node } };
-                layerObject = mergeDeep(layerObject, object);
-                break;
-            }
-            case 'container query block': {
-                // Handle @container queries
-                const selector = joinSelectors(pathParts);
-                const object = { [key]: { [selector]: node } };
-                containerObject = mergeDeep(containerObject, object);
-                break;
-            }
-            case 'media query or prefix': {
-                // Handle media queries and prefixes
-                const selector = joinSelectors(pathParts);
-                const name = key.replace(/^@\s*/, '');
-                if (mediaPrefixes[name]) {
-                    // Handle media prefix
-                    const prefix = mediaPrefixes[name];
-                    const rules = selector ? { ['& ' + selector]: node } : node;
-                    const mediaPrefixObject = { [prefix]: rules };
-                    prefixObject = mergeDeep(prefixObject, mediaPrefixObject);
-                }
-                else {
-                    // Handle media query
-                    let mediaQuery = key;
-                    if (key.startsWith('@media ')) {
-                        // Use the media query as is, just remove @media prefix
-                        mediaQuery = key.replace(/^@media\s+/, '');
-                    }
-                    else if (mediaQueries[name]) {
-                        // Use the named media query from configuration
-                        mediaQuery = mediaQueries[name];
-                    }
-                    else {
-                        // Unknown media query type
-                        console.warn(`Warning: Media query type ${key} is unknown`);
-                        break;
-                    }
-                    // Store the media query with the selector and node
-                    // This way we collect all the rules for each media query
-                    const mediaQueryKey = '@media ' + mediaQuery;
-                    if (!mediaObject[mediaQueryKey]) {
-                        mediaObject[mediaQueryKey] = {};
-                    }
-                    // Add the selector and its rules to this media query
-                    mediaObject[mediaQueryKey] = mergeDeep(mediaObject[mediaQueryKey], { [selector]: node });
-                }
-                break;
-            }
-        }
-        return node;
-    });
-    // Convert the main CSS style object to string
-    let cssString = obj2css(cssStyle);
-    // Add layer statements if any
-    if (layerStatements.length > 0) {
-        cssString = layerStatements.join('\n') + '\n\n' + cssString;
-    }
-    // Process and add layer blocks if any
-    if (Object.keys(layerObject).length > 0) {
-        const layers = Object.keys(layerObject);
-        const layerCssString = layers
-            .map((layer) => {
-            // Type guard for object values
-            const layerStyles = layerObject[layer];
-            if (!isObject(layerStyles))
-                return '';
-            const layerContent = getCss(layerStyles, mediaQueries, mediaPrefixes, auto);
-            return layerContent ? `${layer} {\n${indent(layerContent)}\n}` : '';
-        })
-            .filter(Boolean)
-            .join('\n\n');
-        if (layerCssString) {
-            cssString += '\n\n' + layerCssString;
-        }
-    }
-    // Process and add container queries if any
-    if (Object.keys(containerObject).length > 0) {
-        const containerQueries = Object.keys(containerObject);
-        const containerCssString = containerQueries
-            .map((containerQuery) => {
-            // Type guard for object values
-            const containerStyles = containerObject[containerQuery];
-            if (!isObject(containerStyles))
-                return '';
-            const containerContent = getCss(containerStyles, mediaQueries, mediaPrefixes, auto);
-            return containerContent
-                ? `${containerQuery} {\n${indent(containerContent)}\n}`
-                : '';
-        })
-            .filter(Boolean)
-            .join('\n\n');
-        if (containerCssString) {
-            cssString += '\n\n' + containerCssString;
-        }
-    }
-    // Process and add media queries if any
-    if (Object.keys(mediaObject).length > 0) {
-        const mediaCssString = processMediaQueries(mediaObject, mediaQueries);
-        if (mediaCssString) {
-            cssString += '\n\n' + mediaCssString;
-        }
-    }
-    // Process and add media prefixes if any
-    if (Object.keys(prefixObject).length > 0) {
-        // First, process the prefix object as normal CSS
-        const mediaPrefixedCssString = getCss(prefixObject, mediaQueries, mediaPrefixes);
-        cssString += '\n\n' + mediaPrefixedCssString;
-        // Handle auto mode if configured
-        if (auto) {
-            // Create a modified prefix object for auto mode
-            const autoPrefixObject = {};
-            for (const key of Object.keys(auto)) {
-                const selector = mediaPrefixes[key];
-                if (!selector || !prefixObject[selector])
-                    continue;
-                const [autoSelector, mediaQuery] = auto[key];
-                // Create media query for auto mode
-                autoPrefixObject[`@media ${mediaQuery}`] = {
-                    [autoSelector]: prefixObject[selector],
-                };
-            }
-            // Process the auto prefix object if not empty
-            if (Object.keys(autoPrefixObject).length > 0) {
-                const autoCssString = processMediaQueries(autoPrefixObject, mediaQueries);
-                if (autoCssString) {
-                    cssString += '\n\n' + autoCssString;
-                }
-            }
-        }
-    }
-    // Prettify the final CSS string
-    return prettifyCss(cssString.replace(/__bs__/g, '\\'));
-}
-/**
- * Deep merge two objects
- * @param target - Target object to merge into
- * @param source - Source object to merge from
- * @returns Merged object
- */
-function mergeDeep(target, source) {
-    const output = { ...target };
-    if (isObject(target) && isObject(source)) {
-        Object.keys(source).forEach((key) => {
-            if (isObject(source[key])) {
-                if (!(key in target)) {
-                    output[key] = source[key];
-                }
-                else {
-                    output[key] = mergeDeep(target[key], source[key]);
-                }
-            }
-            else {
-                output[key] = source[key];
-            }
-        });
-    }
-    return output;
-}
-/**
- * Checks if value is a non-null object
- * @param item - Value to check
- * @returns True if the value is a non-null object
- */
-function isObject(item) {
-    return item && typeof item === 'object' && !Array.isArray(item);
-}
-export default getCss;

package/dist/lib/utils/common.d.ts

@@ -1,28 +0,0 @@
-/**
- * Utility functions for CSS processing
- */
-/**
- * Determines the object type in a more precise way than typeof
- * @param obj - Any value to check type
- * @returns The lowercase string representing the object type
- */
-export declare function getObjectType(obj: any): string;
-/**
- * Checks if a value is a primitive end value (string, number, boolean, null)
- * @param value - Value to check
- * @returns True if the value is a primitive end value
- */
-export declare function isEndValue(value: any): boolean;
-/**
- * Indents a string with spaces
- * @param str - String to indent
- * @param spaces - Number of spaces to indent with
- * @returns Indented string
- */
-export declare function indent(str: string, spaces?: number): string;
-/**
- * Converts a JavaScript property name in camelCase to CSS kebab-case
- * @param key - Property name in camelCase
- * @returns Property name in kebab-case
- */
-export declare function jsKeyToCssKey(key: string): string;

package/dist/lib/utils/common.js

@@ -1,47 +0,0 @@
-/**
- * Utility functions for CSS processing
- */
-/**
- * Determines the object type in a more precise way than typeof
- * @param obj - Any value to check type
- * @returns The lowercase string representing the object type
- */
-export function getObjectType(obj) {
-    return (Object.prototype.toString
-        .call(obj)
-        .match(/^\[object (\w+)\]$/)?.[1]
-        .toLowerCase() || 'unknown');
-}
-/**
- * Checks if a value is a primitive end value (string, number, boolean, null)
- * @param value - Value to check
- * @returns True if the value is a primitive end value
- */
-export function isEndValue(value) {
-    return ['string', 'number', 'boolean', 'null'].includes(getObjectType(value));
-}
-/**
- * Indents a string with spaces
- * @param str - String to indent
- * @param spaces - Number of spaces to indent with
- * @returns Indented string
- */
-export function indent(str, spaces = 2) {
-    return str
-        .split('\n')
-        .map((s) => ' '.repeat(spaces) + s)
-        .join('\n');
-}
-/**
- * Converts a JavaScript property name in camelCase to CSS kebab-case
- * @param key - Property name in camelCase
- * @returns Property name in kebab-case
- */
-export function jsKeyToCssKey(key) {
-    // Keep vendor prefixes intact
-    const prefix = key.match(/^[-]+/)?.[0] || '';
-    const baseKey = key.replace(/^[-]+/, '');
-    // Convert camelCase to kebab-case
-    const kebabKey = baseKey.replace(/([A-Z])/g, '-$1').toLowerCase();
-    return prefix + kebabKey;
-}

package/dist/lib/utils/endValue.d.ts

@@ -1,2 +0,0 @@
-import type { IsEndValue } from '../types/index.js';
-export declare const isEndValue: IsEndValue;

package/dist/lib/utils/endValue.js

@@ -1,10 +0,0 @@
-export const isEndValue = (value) => {
-    if (value == null)
-        return false;
-    if (typeof value === 'string' || typeof value === 'number')
-        return true;
-    if (Array.isArray(value)) {
-        return value.every((v) => typeof v === 'string' || typeof v === 'number');
-    }
-    return false;
-};

package/dist/lib/utils/media.d.ts

@@ -1,24 +0,0 @@
-/**
- * Utilities for handling media queries
- */
-import { CssStyles, MediaQueries } from '../types/index.js';
-/**
- * Processes media query objects and converts them to CSS
- * @param mediaObject - Object containing media queries and their styles
- * @param mediaQueries - Named media query definitions
- * @returns CSS string with processed media queries
- */
-export declare function processMediaQueries(mediaObject: CssStyles, mediaQueries?: MediaQueries): string;
-/**
- * Checks if a key represents a media query
- * @param key - Key to check
- * @returns True if the key is a media query
- */
-export declare function isMediaQuery(key: string): boolean;
-/**
- * Checks if a key is a named media query that needs to be resolved
- * @param key - Key to check
- * @param mediaQueries - Named media query definitions
- * @returns True if the key is a named media query
- */
-export declare function isNamedMediaQuery(key: string, mediaQueries: MediaQueries): boolean;

package/dist/lib/utils/media.js

@@ -1,93 +0,0 @@
-/**
- * Utilities for handling media queries
- */
-import { indent, jsKeyToCssKey } from './common.js';
-import { obj2css } from './obj2css.js';
-import { isEndValue } from './common.js';
-/**
- * Processes media query objects and converts them to CSS
- * @param mediaObject - Object containing media queries and their styles
- * @param mediaQueries - Named media query definitions
- * @returns CSS string with processed media queries
- */
-export function processMediaQueries(mediaObject, mediaQueries = {}) {
-    if (!mediaObject || Object.keys(mediaObject).length === 0) {
-        return '';
-    }
-    const mediaQueriesToProcess = Object.keys(mediaObject);
-    // Process each media query and convert to CSS
-    const mediaCssStrings = mediaQueriesToProcess.map((queryKey) => {
-        // Handle named media queries (using @name syntax)
-        const mediaQueryMatch = queryKey.match(/^@(\w+)$/);
-        let actualQuery = queryKey;
-        if (mediaQueryMatch &&
-            mediaQueryMatch[1] &&
-            mediaQueries[mediaQueryMatch[1]]) {
-            // Replace named query with actual query definition
-            actualQuery = mediaQueries[mediaQueryMatch[1]];
-        }
-        else if (queryKey.startsWith('@media ')) {
-            // Strip @media prefix if present
-            actualQuery = queryKey.replace(/^@media\s+/, '');
-        }
-        // Convert the styles for this media query to CSS
-        const styles = mediaObject[queryKey];
-        // Skip if the styles aren't an object
-        if (isEndValue(styles)) {
-            return '';
-        }
-        // Process the styles to convert camelCase properties to kebab-case
-        const processedStyles = processStylesForMedia(styles);
-        const stylesCss = obj2css(processedStyles);
-        if (!stylesCss.trim()) {
-            return '';
-        }
-        // Wrap the styles in a media query block
-        return `@media ${actualQuery} {\n${indent(stylesCss)}\n}`;
-    });
-    // Join all media query blocks with newlines
-    return mediaCssStrings.filter((css) => css).join('\n\n');
-}
-/**
- * Processes styles for media queries to ensure camelCase is converted to kebab-case
- * @param styles - Style object to process
- * @returns Processed style object with converted property names
- */
-function processStylesForMedia(styles) {
-    const result = {};
-    // Process each selector in the styles
-    Object.keys(styles).forEach((selector) => {
-        const selectorStyles = styles[selector];
-        // Skip if not an object
-        if (isEndValue(selectorStyles)) {
-            result[selector] = selectorStyles;
-            return;
-        }
-        const processedProps = {};
-        // Convert each property name to kebab-case
-        Object.keys(selectorStyles).forEach((prop) => {
-            const cssKey = jsKeyToCssKey(prop);
-            processedProps[cssKey] = selectorStyles[prop];
-        });
-        result[selector] = processedProps;
-    });
-    return result;
-}
-/**
- * Checks if a key represents a media query
- * @param key - Key to check
- * @returns True if the key is a media query
- */
-export function isMediaQuery(key) {
-    return key.startsWith('@media') || key.startsWith('@');
-}
-/**
- * Checks if a key is a named media query that needs to be resolved
- * @param key - Key to check
- * @param mediaQueries - Named media query definitions
- * @returns True if the key is a named media query
- */
-export function isNamedMediaQuery(key, mediaQueries) {
-    const match = key.match(/^@(\w+)$/);
-    return Boolean(match && match[1] && mediaQueries[match[1]]);
-}

package/dist/lib/utils/obj2css.d.ts

@@ -1,15 +0,0 @@
-/**
- * Utilities for converting JavaScript objects to CSS strings
- */
-/**
- * Converts a CSS object to a string representation
- * @param cssObject - Object with CSS selectors and properties
- * @returns CSS string
- */
-export declare function obj2css(cssObject: Record<string, any>): string;
-/**
- * Prettifies a CSS string by ensuring consistent spacing and formatting
- * @param cssString - CSS string to prettify
- * @returns Prettified CSS string
- */
-export declare function prettifyCss(cssString: string): string;