esm-styles 0.3.7 → 0.3.9

package/dist/lib/build.js

@@ -257,7 +257,8 @@ export async function build(configPath = 'esm-styles.config.js') {
         '\n';
     await fs.writeFile(mainCssPath, mainCss, 'utf8');
     // 6. Create timestamp file
-    const timestampPath = path.join(config.basePath || '.', config.timestampOutputPath || '', 'timestamp.mjs');
+    const { outputPath: timestampOutputPath, extension: timestampExtension } = config.timestamp || { outputPath: '', extension: 'mjs' };
+    const timestampPath = path.join(config.basePath || '.', timestampOutputPath, 'timestamp.' + timestampExtension);
     await fs.writeFile(timestampPath, `export default ${Date.now()}`, 'utf8');
 }
 // Helper for file URL import

package/dist/lib/utils/selector.js

@@ -179,6 +179,25 @@ export const isClassSelector = (key) => {
     // _foo = class, __foo = descendant class
     return key.startsWith('_');
 };
+const processClass = (cls) => {
+    if (/^[A-Z]/.test(cls)) {
+        return cls;
+    }
+    // Custom kebab conversion:
+    // 1. Handle camelCase (e.g. myClass -> my-Class)
+    // 2. Handle snake_case (e.g. my_class -> my-class)
+    // 3. Lowercase everything (my-Class -> my-class)
+    // We do NOT use lodash/kebabCase because it splits numbers (i1 -> i-1), which is undesirable
+    return cls
+        .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+        .replace(/_/g, '-')
+        .toLowerCase();
+};
+const transformExplicitClasses = (selector) => {
+    return selector.replace(/\.([a-zA-Z0-9_-]+)/g, (_, cls) => {
+        return '.' + processClass(cls);
+    });
+};
 export const joinSelectorPath = (path) => {
     // Compute cartesian product of all segments
     const combos = utils.cartesianProduct(path);
@@ -187,64 +206,84 @@ export const joinSelectorPath = (path) => {
         // Check if previous part is a root selector
         const prev = idx > 0 ? parts[idx - 1] : null;
         const isPrevRoot = prev && (prev === ':root' || prev.startsWith(':root.'));
-        if (part === '*') {
-            // Universal selector
-            return acc + (acc ? ' ' : '') + '*';
-        }
-        else if (part.startsWith('__')) {
-            return acc + (acc ? ' ' : '') + '.' + part.slice(2);
-        }
-        else if (part.startsWith('_')) {
-            // Attach class directly to previous part unless prev is combinator or root
-            const combinators = ['>', '+', '~'];
-            const isPrevCombinator = prev && combinators.some((c) => prev.startsWith(c));
-            if (isPrevRoot || isPrevCombinator || !acc) {
-                return acc + (acc ? ' ' : '') + '.' + part.slice(1);
+        switch (true) {
+            case part === '*':
+                // Universal selector
+                return acc + (acc ? ' ' : '') + '*';
+            case part.startsWith('__'): {
+                const content = part.slice(2);
+                const match = content.match(/^([a-zA-Z0-9_-]+)(.*)$/);
+                let processed = '';
+                if (match) {
+                    processed =
+                        processClass(match[1]) + transformExplicitClasses(match[2]);
+                }
+                else {
+                    processed = processClass(content);
+                }
+                return acc + (acc ? ' ' : '') + '.' + processed;
             }
-            else {
+            case part.startsWith('_'): {
+                // Attach class directly to previous part unless prev is combinator or root
+                const content = part.slice(1);
+                const match = content.match(/^([a-zA-Z0-9_-]+)(.*)$/);
+                let processed = '';
+                if (match) {
+                    processed =
+                        processClass(match[1]) + transformExplicitClasses(match[2]);
+                }
+                else {
+                    processed = processClass(content);
+                }
+                const combinators = ['>', '+', '~'];
+                const isPrevCombinator = prev && combinators.some((c) => prev.startsWith(c));
+                if (isPrevRoot || isPrevCombinator || !acc) {
+                    return acc + (acc ? ' ' : '') + '.' + processed;
+                }
                 // Attach directly (no space)
-                return acc + '.' + part.slice(1);
-            }
-        }
-        else if (part.startsWith('>') ||
-            part.startsWith('+') ||
-            part.startsWith('~')) {
-            // Combinators: always join with a space
-            return acc + ' ' + part;
-        }
-        else if (part.startsWith(':') ||
-            part.startsWith('::') ||
-            part.startsWith('#') ||
-            part.startsWith('[') ||
-            part.startsWith('.')) {
-            return acc + part;
-        }
-        else if (isHtmlTag(part)) {
-            return acc + (acc ? ' ' : '') + part;
-        }
-        else if (startsWithHtmlTag(part)) {
-            // Handle compound selectors that start with HTML tags (e.g., 'div > *')
-            return acc + (acc ? ' ' : '') + part;
-        }
-        else if (/^([a-z][a-z0-9]*)\.(.+)/.test(part)) {
-            // If part matches 'tag.class...' and tag is an HTML tag
-            const match = part.match(/^([a-z][a-z0-9]*)\.(.+)/);
-            if (match && isHtmlTag(match[1])) {
-                return acc + (acc ? ' ' : '') + match[1] + '.' + match[2];
+                return acc + '.' + processed;
             }
+            case part.startsWith('>') ||
+                part.startsWith('+') ||
+                part.startsWith('~'):
+                // Combinators: always join with a space
+                return acc + ' ' + part;
+            case part.startsWith(':') ||
+                part.startsWith('::') ||
+                part.startsWith('#') ||
+                part.startsWith('[') ||
+                part.startsWith('.'):
+                return acc + transformExplicitClasses(part);
+            case isHtmlTag(part):
+                return acc + (acc ? ' ' : '') + part;
+            case startsWithHtmlTag(part):
+                // Handle compound selectors that start with HTML tags (e.g., 'div > *')
+                return acc + (acc ? ' ' : '') + transformExplicitClasses(part);
+            case /^[a-z][a-z0-9]*\.(.+)/.test(part) &&
+                isHtmlTag(part.split('.')[0]):
+                // If part matches 'tag.class...' and tag is an HTML tag
+                return acc + (acc ? ' ' : '') + transformExplicitClasses(part);
+            case /^[a-z][a-z0-9]*#[\w-]+$/.test(part) &&
+                isHtmlTag(part.split('#')[0]):
+                // If part matches 'tag#id' and tag is an HTML tag
+                // ID should technically not be kebab-cased, and regex ensures no classes.
+                return acc + (acc ? ' ' : '') + part;
+            default:
+                // Not a tag, not a special selector: treat as class or custom element
+                let processedPart = part;
+                const match = part.match(/^([a-zA-Z0-9_-]+)(.*)$/);
+                if (match) {
+                    processedPart =
+                        processClass(match[1]) + transformExplicitClasses(match[2]);
+                }
+                else {
+                    processedPart = transformExplicitClasses(part);
+                }
+                // If previous part is a root selector, insert a space
+                if (isPrevRoot) {
+                    return acc + ' ' + '.' + processedPart;
+                }
+                return acc + '.' + processedPart;
         }
-        else if (/^([a-z][a-z0-9]*)#([\w-]+)$/.test(part)) {
-            // If part matches 'tag#id' and tag is an HTML tag
-            const match = part.match(/^([a-z][a-z0-9]*)#([\w-]+)$/);
-            if (match && isHtmlTag(match[1])) {
-                return acc + (acc ? ' ' : '') + match[1] + '#' + match[2];
-            }
-        }
-        // Not a tag, not a special selector: treat as class or custom element
-        // If previous part is a root selector, insert a space
-        if (isPrevRoot) {
-            return acc + ' ' + '.' + part;
-        }
-        return acc + (acc ? '' : '') + '.' + part;
     }, ''));
 };

package/doc/usage-guide.md

@@ -144,21 +144,21 @@ export default {
 
 ### Configuration Properties
 
-| Property              | Description                                                               |
-| --------------------- | ------------------------------------------------------------------------- |
-| `basePath`            | Base directory for all styles, relative to where the build command is run |
-| `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`)                    |
-| `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`)                        |
-| `media`               | Object defining media types and their variable sets                       |
-| `mediaSelectors`      | Configuration for applying media types with selectors/queries             |
-| `mediaQueries`        | Object defining shorthand names for media queries                         |
-| `timestampOutputPath` | Path where timestamp.mjs file will be written (default: `basePath`)       |
+| Property             | Description                                                                     |
+| -------------------- | ------------------------------------------------------------------------------- |
+| `basePath`           | Base directory for all styles, relative to where the build command is run       |
+| `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`)                          |
+| `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`)                              |
+| `media`              | Object defining media types and their variable sets                             |
+| `mediaSelectors`     | Configuration for applying media types with selectors/queries                   |
+| `mediaQueries`       | Object defining shorthand names for media queries                               |
+| `timestamp`          | Configuration for timestamp.mjs file (default: `basePath` and `.mjs` extension) |
 
 ## JS to CSS Translation Rules
 
@@ -319,6 +319,24 @@ Use commas to target multiple selectors:
 }
 ```
 
+### T9: Automatic Kebab-case Conversion
+
+Class names in selectors are automatically converted from camelCase to kebab-case, unless they are PascalCase (starting with an uppercase letter), in which case they are preserved as-is.
+
+```js
+{
+  myClass: {          // Becomes .my-class
+    color: 'red'
+  },
+  'myClass:hover': {  // Becomes .my-class:hover
+    color: 'blue'
+  },
+  MyComponent: {      // Becomes .MyComponent (preserved)
+    color: 'green'
+  }
+}
+```
+
 ## Floors and Layers
 
 ESM Styles supports @layer directives through its floors configuration system.
@@ -652,3 +670,21 @@ The supporting modules provide:
 
 - Autocomplete for available variables in most code editors
 - The ability to see the actual values for each theme or device
+
+## Timestamp file
+
+ESM Styles generate a timestamp file to track the last build time. This can be useful for caching and versioning, or to trigger HMR when in development mode.
+
+```js
+// timestamp.mjs (generated)
+export default 1767867956228
+```
+
+### Configuration in esm-styles.config.mjs
+
+By default, the timestamp file is put to the root of the `basePath` directory with `.mjs` extension.
+
+```js
+  // put timestamp file to [basePath]/source folder with .ts extension
+  timestamp: { outputPath: 'source', extension: 'ts' },
+```

package/package.json

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