esm-styles 0.3.12 → 0.4.1

package/README.md

@@ -181,6 +181,11 @@ export default {
     hover: '(hover: hover)',
     // ...whatever you want
   },
+
+  // Import aliases (optional) - replace long relative paths with short prefixes
+  aliases: {
+    '@': '.', // resolves relative to sourcePath
+  },
 }
 ```
 
@@ -451,6 +456,50 @@ The build process wraps floors in their respective layers and generates a main C
 
 Missing variables in one theme automatically inherit from the previous theme in the configuration.
 
+### Import Aliases
+
+Simplify imports in your style files by configuring path aliases:
+
+```js
+// esm-styles.config.js
+export default {
+  // ...
+  aliases: {
+    '@': '.',           // @ resolves to sourcePath
+    '@components': './components',
+  },
+}
+```
+
+Then use in your style files:
+
+```js
+// Before (relative paths)
+import $theme from '../../$theme.mjs'
+import { button } from '../components/button.styles.mjs'
+
+// After (with aliases)
+import $theme from '@/$theme.mjs'
+import { button } from '@components/button.styles.mjs'
+```
+
+Alias paths are resolved relative to the `sourcePath` directory. This feature uses esbuild internally for fast module resolution.
+
+#### IDE Support for Aliases
+
+To enable Cmd+click navigation and IntelliSense for aliased imports, create a `jsconfig.json` in your styles source directory with matching path mappings:
+
+```json
+{
+  "compilerOptions": {
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["./*"]
+    }
+  }
+}
+```
+
 ## Additional documentation
 
 For humans: [doc/usage-guide.md](doc/usage-guide.md)

package/dist/lib/build.js

@@ -7,6 +7,64 @@ import fs from 'node:fs/promises';
 // import { inspect } from 'node:util'
 import _ from 'lodash';
 import * as esbuild from 'esbuild';
+/**
+ * Create an esbuild plugin for path alias resolution.
+ * Handles prefixes like '@/' -> './source/'
+ */
+function createAliasPlugin(aliases, sourcePath) {
+    // Sort aliases by length (longest first) to match most specific first
+    const sortedAliases = Object.entries(aliases).sort(([a], [b]) => b.length - a.length);
+    return {
+        name: 'esm-styles-alias',
+        setup(build) {
+            // Match any import that starts with one of our alias prefixes
+            const aliasPattern = new RegExp(`^(${sortedAliases.map(([key]) => escapeRegex(key)).join('|')})(/.*)?$`);
+            build.onResolve({ filter: aliasPattern }, (args) => {
+                for (const [alias, target] of sortedAliases) {
+                    if (args.path === alias || args.path.startsWith(alias + '/')) {
+                        const rest = args.path.slice(alias.length); // includes leading '/' or empty
+                        const resolvedTarget = path.resolve(sourcePath, target);
+                        const resolvedPath = path.join(resolvedTarget, rest);
+                        return { path: resolvedPath };
+                    }
+                }
+                return null;
+            });
+        },
+    };
+}
+/**
+ * Escape special regex characters in a string
+ */
+function escapeRegex(str) {
+    return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/**
+ * Import a module with alias resolution using esbuild.
+ * Falls back to direct import when no aliases are configured.
+ */
+async function importWithAliases(filePath, aliases, sourcePath) {
+    // If no aliases configured, use direct import with cache-busting
+    if (!aliases || Object.keys(aliases).length === 0) {
+        const fileUrl = pathToFileUrl(filePath).href + `?update=${Date.now()}`;
+        return import(fileUrl);
+    }
+    // Use esbuild to bundle with alias resolution via plugin
+    const result = await esbuild.build({
+        entryPoints: [filePath],
+        bundle: true,
+        write: false,
+        format: 'esm',
+        platform: 'node',
+        plugins: [createAliasPlugin(aliases, sourcePath)],
+        // Prevent esbuild from trying to resolve node_modules
+        packages: 'external',
+    });
+    // Import from data URL to avoid filesystem caching
+    const code = result.outputFiles[0].text;
+    const dataUrl = `data:text/javascript;base64,${Buffer.from(code).toString('base64')}`;
+    return import(dataUrl);
+}
 export async function build(configPath = 'esm-styles.config.js') {
     // --- Supporting module generation ---
     // Debug: log mergedSets and sets
@@ -23,6 +81,7 @@ export async function build(configPath = 'esm-styles.config.js') {
     const suffix = config.sourceFilesSuffix || '.styles.mjs';
     const floors = config.floors || [];
     const mainCssFile = config.mainCssFile || 'styles.css';
+    const aliases = config.aliases;
     // Helper function to generate CSS comment header
     const generateCssComment = (sourceName) => {
         const normalizedBasePath = (config.basePath || '.').replace(/^\.*\//, '');
@@ -38,8 +97,8 @@ export async function build(configPath = 'esm-styles.config.js') {
     if (config.globalVariables) {
         const inputFile = path.join(sourcePath, `${config.globalVariables}${suffix}`);
         const outputFile = path.join(outputPath, `global.css`);
-        const fileUrl = pathToFileUrl(inputFile).href + `?update=${Date.now()}`;
-        const varsObj = (await import(fileUrl)).default;
+        const varsObj = (await importWithAliases(inputFile, aliases, sourcePath))
+            .default;
         const cssVars = getCssVariables(varsObj);
         const rootSelector = config.globalRootSelector || ':root';
         const comment = generateCssComment(config.globalVariables);
@@ -57,8 +116,7 @@ export async function build(configPath = 'esm-styles.config.js') {
             for (const setName of sets) {
                 // Inheritance: merge with previous
                 const inputFile = path.join(sourcePath, `${setName}${suffix}`);
-                const fileUrl = pathToFileUrl(inputFile).href + `?update=${Date.now()}`;
-                const varsObj = _.merge({}, prevVarsObj, (await import(fileUrl)).default);
+                const varsObj = _.merge({}, prevVarsObj, (await importWithAliases(inputFile, aliases, sourcePath)).default);
                 prevVarsObj = varsObj;
                 mergedSets[setName] = _.cloneDeep(varsObj);
                 // For each selector config for this set
@@ -187,8 +245,8 @@ export async function build(configPath = 'esm-styles.config.js') {
         // Ensure the output directory exists
         await fs.mkdir(floorOutputDir, { recursive: true });
         const outputFile = path.join(floorOutputDir, `${source}.css`);
-        const fileUrl = pathToFileUrl(inputFile).href + `?update=${Date.now()}`;
-        const stylesObj = (await import(fileUrl)).default;
+        const stylesObj = (await importWithAliases(inputFile, aliases, sourcePath))
+            .default;
         const css = getCss(stylesObj, {
             ...mediaShorthands,
             globalRootSelector: config.globalRootSelector,

package/dist/lib/types/styles.d.ts

@@ -0,0 +1,183 @@
+/**
+ * ESM Styles - TypeScript definitions for style objects
+ *
+ * Provides type safety and autocompletion for CSS properties
+ * while maintaining the flexible, nested syntax of esm-styles.
+ */
+import type { Properties } from 'csstype';
+/**
+ * CSS variable reference object (as generated by $theme/$device modules)
+ */
+export interface CSSVariableRef {
+    var: string;
+    name?: string;
+    [key: string]: string | undefined;
+}
+/**
+ * Value that can be used for any CSS property
+ */
+export type CSSValue = string | number | CSSVariableRef;
+/**
+ * CSS Properties with support for CSS variable references
+ * Using csstype's Properties as base with extended value types
+ */
+export type CSSProperties = {
+    [K in keyof Properties]?: Properties[K] | CSSValue;
+};
+/**
+ * Common pseudo-class and pseudo-element keys for better autocompletion
+ */
+export type CommonPseudos = ':hover' | ':active' | ':focus' | ':focus-visible' | ':focus-within' | ':visited' | ':disabled' | ':enabled' | ':checked' | ':first-child' | ':last-child' | ':nth-child' | ':not' | ':has' | '::before' | '::after' | '::placeholder' | '::selection' | '::first-line' | '::first-letter';
+/**
+ * Complete style object type.
+ *
+ * Due to TypeScript limitations with index signatures,
+ * we use a permissive approach that still provides
+ * autocompletion for CSS properties while allowing
+ * nested selectors.
+ *
+ * The tradeoff: typos in CSS property names won't be caught,
+ * but you get full autocompletion when typing.
+ */
+export type StyleObject = CSSProperties & {
+    [K in CommonPseudos]?: StyleObject;
+} & {
+    [selector: string]: StyleObject | CSSValue | string | undefined;
+};
+/**
+ * Root-level stylesheet with named selectors
+ */
+export type StyleSheet = {
+    [selector: string]: StyleObject;
+};
+/**
+ * Strict CSS properties without nested selectors.
+ * Use this for leaf-level style objects where you want
+ * full type checking and no nested selectors are needed.
+ */
+export type StrictCSSProperties = {
+    [K in keyof Properties]?: Properties[K] | CSSValue;
+};
+/**
+ * Strict style object with explicit nested selector type.
+ * Provides better type checking at the cost of more verbose syntax.
+ */
+export interface StrictStyleObject extends StrictCSSProperties {
+    ':hover'?: StrictStyleObject;
+    ':active'?: StrictStyleObject;
+    ':focus'?: StrictStyleObject;
+    ':focus-visible'?: StrictStyleObject;
+    ':disabled'?: StrictStyleObject;
+    '::before'?: StrictStyleObject;
+    '::after'?: StrictStyleObject;
+    '::placeholder'?: StrictStyleObject;
+}
+/**
+ * Define a typed stylesheet with autocompletion.
+ *
+ * @example
+ * ```ts
+ * import { defineStyles } from 'esm-styles'
+ * import $theme from './$theme'
+ *
+ * export default defineStyles({
+ *   button: {
+ *     backgroundColor: $theme.paper.bright,
+ *     padding: '12px 24px',
+ *
+ *     ':hover': {
+ *       opacity: 0.9,
+ *     },
+ *
+ *     '@dark': {
+ *       backgroundColor: $theme.paper.tinted,
+ *     },
+ *
+ *     __icon: {
+ *       width: '20px',
+ *     },
+ *   },
+ * })
+ * ```
+ */
+export declare function defineStyles<T extends StyleSheet>(styles: T): T;
+/**
+ * Define a component style for named export.
+ * Use this in component files that are imported into floor modules.
+ *
+ * @example
+ * ```ts
+ * // button.styles.ts
+ * import { defineComponent } from 'esm-styles'
+ * import $theme from './$theme'
+ *
+ * export const button = defineComponent({
+ *   padding: '12px 24px',
+ *   backgroundColor: $theme.paper.bright,
+ *
+ *   ':hover': { opacity: 0.9 },
+ *   '@dark': { backgroundColor: $theme.paper.tinted },
+ *
+ *   primary: { backgroundColor: 'blue' },
+ *   __icon: { width: '20px' },
+ * })
+ * ```
+ *
+ * ```ts
+ * // components.styles.ts (floor module)
+ * import { defineStyles } from 'esm-styles'
+ * import { button } from './button.styles'
+ *
+ * export default defineStyles({ button })
+ * ```
+ */
+export declare function defineComponent<T extends StyleObject>(styles: T): T;
+/**
+ * Define a reusable style mixin (for spreading into other styles).
+ *
+ * @example
+ * ```ts
+ * import { defineMixin } from 'esm-styles'
+ *
+ * export const flexCenter = defineMixin({
+ *   display: 'flex',
+ *   alignItems: 'center',
+ *   justifyContent: 'center',
+ * })
+ *
+ * // Usage:
+ * export const card = defineComponent({
+ *   ...flexCenter,
+ *   padding: '24px',
+ * })
+ * ```
+ */
+export declare function defineMixin<T extends StyleObject>(mixin: T): T;
+/**
+ * Define strict CSS properties (no nesting, full type checking).
+ * Use for simple style objects where you want maximum type safety.
+ *
+ * @example
+ * ```ts
+ * const buttonBase = defineStrict({
+ *   display: 'inline-flex',
+ *   padding: '12px 24px',
+ *   // backgroundColr: 'red',  // ❌ TypeScript error!
+ * })
+ * ```
+ */
+export declare function defineStrict<T extends StrictCSSProperties>(styles: T): T;
+/**
+ * Leaf token with CSS variable reference
+ */
+export interface ThemeToken extends CSSVariableRef {
+    var: string;
+    name: string;
+}
+/**
+ * Nested theme tokens structure
+ */
+export type ThemeTokens = {
+    [key: string]: ThemeToken | ThemeTokens;
+};
+export type { Properties, Pseudos } from 'csstype';

package/dist/lib/types/styles.js

@@ -0,0 +1,112 @@
+/**
+ * ESM Styles - TypeScript definitions for style objects
+ *
+ * Provides type safety and autocompletion for CSS properties
+ * while maintaining the flexible, nested syntax of esm-styles.
+ */
+// ============================================
+// Helper Functions
+// ============================================
+/**
+ * Define a typed stylesheet with autocompletion.
+ *
+ * @example
+ * ```ts
+ * import { defineStyles } from 'esm-styles'
+ * import $theme from './$theme'
+ *
+ * export default defineStyles({
+ *   button: {
+ *     backgroundColor: $theme.paper.bright,
+ *     padding: '12px 24px',
+ *
+ *     ':hover': {
+ *       opacity: 0.9,
+ *     },
+ *
+ *     '@dark': {
+ *       backgroundColor: $theme.paper.tinted,
+ *     },
+ *
+ *     __icon: {
+ *       width: '20px',
+ *     },
+ *   },
+ * })
+ * ```
+ */
+export function defineStyles(styles) {
+    return styles;
+}
+/**
+ * Define a component style for named export.
+ * Use this in component files that are imported into floor modules.
+ *
+ * @example
+ * ```ts
+ * // button.styles.ts
+ * import { defineComponent } from 'esm-styles'
+ * import $theme from './$theme'
+ *
+ * export const button = defineComponent({
+ *   padding: '12px 24px',
+ *   backgroundColor: $theme.paper.bright,
+ *
+ *   ':hover': { opacity: 0.9 },
+ *   '@dark': { backgroundColor: $theme.paper.tinted },
+ *
+ *   primary: { backgroundColor: 'blue' },
+ *   __icon: { width: '20px' },
+ * })
+ * ```
+ *
+ * ```ts
+ * // components.styles.ts (floor module)
+ * import { defineStyles } from 'esm-styles'
+ * import { button } from './button.styles'
+ *
+ * export default defineStyles({ button })
+ * ```
+ */
+export function defineComponent(styles) {
+    return styles;
+}
+/**
+ * Define a reusable style mixin (for spreading into other styles).
+ *
+ * @example
+ * ```ts
+ * import { defineMixin } from 'esm-styles'
+ *
+ * export const flexCenter = defineMixin({
+ *   display: 'flex',
+ *   alignItems: 'center',
+ *   justifyContent: 'center',
+ * })
+ *
+ * // Usage:
+ * export const card = defineComponent({
+ *   ...flexCenter,
+ *   padding: '24px',
+ * })
+ * ```
+ */
+export function defineMixin(mixin) {
+    return mixin;
+}
+/**
+ * Define strict CSS properties (no nesting, full type checking).
+ * Use for simple style objects where you want maximum type safety.
+ *
+ * @example
+ * ```ts
+ * const buttonBase = defineStrict({
+ *   display: 'inline-flex',
+ *   padding: '12px 24px',
+ *   // backgroundColr: 'red',  // ❌ TypeScript error!
+ * })
+ * ```
+ */
+export function defineStrict(styles) {
+    return styles;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "esm-styles",
-  "version": "0.3.12",
+  "version": "0.4.1",
   "description": "A library for working with ESM styles",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -49,6 +49,7 @@
     "typescript": "^5.8.3"
   },
   "dependencies": {
+    "csstype": "^3.2.3",
     "esbuild": "^0.27.2",
     "js-beautify": "^1.15.4"
   },