esm-styles 0.4.0 → 0.4.1

package/dist/lib/build.js

@@ -7,6 +7,38 @@ 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.
@@ -17,19 +49,14 @@ async function importWithAliases(filePath, aliases, sourcePath) {
         const fileUrl = pathToFileUrl(filePath).href + `?update=${Date.now()}`;
         return import(fileUrl);
     }
-    // Resolve aliases relative to sourcePath
-    const resolvedAliases = {};
-    for (const [key, value] of Object.entries(aliases)) {
-        resolvedAliases[key] = path.resolve(sourcePath, value);
-    }
-    // Use esbuild to bundle with alias resolution
+    // Use esbuild to bundle with alias resolution via plugin
     const result = await esbuild.build({
         entryPoints: [filePath],
         bundle: true,
         write: false,
         format: 'esm',
         platform: 'node',
-        alias: resolvedAliases,
+        plugins: [createAliasPlugin(aliases, sourcePath)],
         // Prevent esbuild from trying to resolve node_modules
         packages: 'external',
     });

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.4.0",
+  "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"
   },