esm-styles 0.1.12 → 0.2.0

package/doc/ai-guide.md

@@ -0,0 +1,221 @@
+# ESM Styles AI Reference
+
+## Core Patterns
+
+### Basic Style Object to CSS
+
+```js
+// Input
+{
+  button: {
+    backgroundColor: 'blue',
+    color: 'white',
+    padding: '10px 20px'
+  }
+}
+
+// Output CSS
+button {
+  background-color: blue;
+  color: white;
+  padding: 10px 20px;
+}
+```
+
+### HTML Tags vs Class Selectors
+
+```js
+// Tags are recognized directly
+{
+  div: { margin: '0' },          // -> div { margin: 0; }
+  p: { fontSize: '16px' },       // -> p { font-size: 16px; }
+
+  // Non-HTML tags become class selectors
+  header: { display: 'flex' },   // -> .header { display: flex; }
+  card: { padding: '20px' }      // -> .card { padding: 20px; }
+}
+```
+
+### Nesting
+
+```js
+{
+  nav: {
+    backgroundColor: '#333',
+
+    ul: {
+      display: 'flex',
+
+      li: {
+        margin: '0 10px',
+
+        a: {
+          color: 'white'
+        }
+      }
+    }
+  }
+}
+
+// Output: Proper nested selectors
+// nav { background-color: #333; }
+// nav ul { display: flex; }
+// nav ul li { margin: 0 10px; }
+// nav ul li a { color: white; }
+```
+
+### Underscore Conventions
+
+```js
+{
+  div: {
+    // Single underscore: force class selector for tag name
+    _p: { fontWeight: 'bold' },      // -> div.p { font-weight: bold; }
+
+    // Double underscore: descendant selector
+    __icon: { width: '20px' }        // -> div .icon { width: 20px; }
+  }
+}
+```
+
+### Pseudo-Classes and Special Selectors
+
+```js
+{
+  button: {
+    ':hover': { opacity: 0.9 },                // -> button:hover { opacity: 0.9; }
+    '::before': { content: '"→"' },            // -> button::before { content: "→"; }
+    '> span': { marginLeft: '5px' },           // -> button > span { margin-left: 5px; }
+    '[disabled]': { cursor: 'not-allowed' }    // -> button[disabled] { cursor: not-allowed; }
+  }
+}
+```
+
+### Multiple Selectors
+
+```js
+{
+  'h1, h2, h3': {
+    margin: '0 0 1rem'
+  },
+
+  'input[type="text"], input[type="email"]': {
+    padding: '8px'
+  }
+}
+```
+
+### Media Queries
+
+```js
+{
+  container: {
+    maxWidth: '1200px',
+
+    '@media (max-width: 768px)': {
+      maxWidth: '100%'
+    },
+
+    '@tablet': {                 // Uses named query from config
+      padding: '0 20px'
+    }
+  }
+}
+```
+
+### Theme Variants
+
+```js
+{
+  button: {
+    backgroundColor: 'white',
+
+    '@dark': {                   // Applies to :root.dark selector
+      backgroundColor: '#222'
+    }
+  }
+}
+```
+
+## Using CSS Variables
+
+### CSS Variable Module Pattern
+
+```js
+// Import module generated by build process
+import $theme from './$theme.mjs'
+
+export default {
+  button: {
+    // Use variable references - gets converted to var(--color-primary)
+    backgroundColor: $theme.color.primary,
+    color: $theme.color.textOnPrimary,
+  },
+}
+```
+
+### CSS Variable Objects
+
+```js
+// All objects with `var` property are treated as CSS variable references
+{
+  button: {
+    backgroundColor: { var: '--color-primary' }
+  }
+}
+// -> button { background-color: var(--color-primary); }
+```
+
+## CLI Usage
+
+```bash
+# Build with default config
+npx esm-styles build
+
+# Build with custom config
+npx esm-styles build path/to/config.js
+```
+
+## Config Pattern
+
+```js
+// Essential config pattern
+export default {
+  basePath: './src/styles',
+  sourcePath: 'source',
+  outputPath: 'css',
+  layers: ['base', 'components', 'utilities'],
+  mainCssFile: 'styles.css',
+
+  // Media shorthand definitions
+  mediaQueries: {
+    mobile: '(max-width: 767px)',
+    tablet: '(min-width: 768px) and (max-width: 1024px)',
+    desktop: '(min-width: 1025px)',
+  },
+
+  // Theme setup
+  media: {
+    theme: ['light', 'dark'],
+  },
+
+  mediaSelectors: {
+    theme: {
+      light: [
+        { selector: '.light' },
+        {
+          selector: '.auto',
+          mediaQuery: 'screen and (prefers-color-scheme: light)',
+        },
+      ],
+      dark: [
+        { selector: '.dark' },
+        {
+          selector: '.auto',
+          mediaQuery: 'screen and (prefers-color-scheme: dark)',
+        },
+      ],
+    },
+  },
+}
+```

package/doc/api-reference.md

@@ -0,0 +1,262 @@
+# ESM Styles API Reference
+
+This document provides a comprehensive overview of the API for ESM Styles, detailing the core functionality and configuration options.
+
+## Table of Contents
+
+- [Core API](#core-api)
+  - [getCss](#getcss)
+- [Configuration](#configuration)
+  - [Configuration Object](#configuration-object)
+  - [Media Selectors](#media-selectors)
+  - [Media Queries](#media-queries)
+- [CLI Commands](#cli-commands)
+  - [build](#build)
+
+## Core API
+
+### getCss
+
+```typescript
+function getCss(styles: CssJsObject, options?: GetCssOptions): CssString
+```
+
+The main function that converts a JavaScript/TypeScript object into a CSS string.
+
+#### Parameters
+
+- `styles`: A JavaScript object representing CSS styles.
+- `options`: (Optional) Configuration options for CSS generation.
+
+#### Returns
+
+A string containing the generated CSS.
+
+#### Example
+
+```javascript
+import { getCss } from 'esm-styles'
+
+const styles = {
+  button: {
+    backgroundColor: '#4285f4',
+    color: 'white',
+    padding: '10px 20px',
+
+    ':hover': {
+      backgroundColor: '#3367d6',
+    },
+  },
+}
+
+const css = getCss(styles)
+console.log(css)
+// Outputs: button { background-color: #4285f4; color: white; padding: 10px 20px; } button:hover { background-color: #3367d6; }
+```
+
+### Types
+
+#### CssJsObject
+
+```typescript
+type CssJsObject = {
+  [key: string]:
+    | CssJsObject
+    | string
+    | number
+    | boolean
+    | null
+    | undefined
+    | { var: string }
+}
+```
+
+Represents a JavaScript object structure that can be converted to CSS.
+
+#### GetCssOptions
+
+```typescript
+interface GetCssOptions {
+  globalRootSelector?: string
+  mediaQueries?: Record<string, string>
+  selectorShorthands?: Record<
+    string,
+    Array<{
+      selector?: string
+      mediaQuery?: string
+    }>
+  >
+}
+```
+
+Configuration options for the CSS generation process:
+
+- `globalRootSelector`: Root selector for variables (default: ':root')
+- `mediaQueries`: Map of named media query shorthands
+- `selectorShorthands`: Map of named selector shorthands
+
+#### CssString
+
+```typescript
+type CssString = string
+```
+
+A string containing valid CSS.
+
+#### CssRuleObject
+
+```typescript
+interface CssRuleObject {
+  [key: string]: string | number
+}
+```
+
+Represents a set of CSS property declarations.
+
+## Configuration
+
+### Configuration Object
+
+The `esm-styles.config.js` file exports a configuration object with the following structure:
+
+```typescript
+interface ESMStylesConfig {
+  // Paths
+  basePath: string
+  sourcePath: string
+  outputPath: string
+  sourceFilesSuffix?: string
+
+  // Input
+  layers: string[]
+
+  // Output
+  mainCssFile: string
+
+  // Variables
+  globalVariables?: string
+  globalRootSelector?: string
+
+  // Media
+  media?: Record<string, string[]>
+  mediaSelectors?: Record<string, Record<string, Array<MediaSelectorConfig>>>
+  mediaQueries?: Record<string, string>
+}
+```
+
+#### 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  | -             |
+
+### Media Selectors
+
+The `mediaSelectors` configuration defines how variables should be applied in different contexts:
+
+```typescript
+interface MediaSelectorConfig {
+  selector?: string
+  mediaQuery?: string
+  prefix?: string
+}
+```
+
+#### Properties
+
+| Property     | Type   | Description                             |
+| ------------ | ------ | --------------------------------------- |
+| `selector`   | string | CSS selector to append to root selector |
+| `mediaQuery` | string | Media query for conditional application |
+| `prefix`     | string | Prefix for generated CSS file names     |
+
+#### Example
+
+```javascript
+mediaSelectors: {
+  theme: {
+    dark: [
+      // Applied when .dark class is present
+      {
+        selector: '.dark',
+      },
+      // Applied in dark mode when .auto class is present
+      {
+        selector: '.auto',
+        mediaQuery: 'screen and (prefers-color-scheme: dark)',
+        prefix: 'auto',
+      },
+    ]
+  }
+}
+```
+
+### Media Queries
+
+The `mediaQueries` configuration provides shorthands for commonly used media queries:
+
+```javascript
+mediaQueries: {
+  'mobile': '(max-width: 767px)',
+  'tablet': '(min-width: 768px) and (max-width: 1024px)',
+  'desktop': '(min-width: 1025px)'
+}
+```
+
+These shorthands can be used directly in style objects:
+
+```javascript
+{
+  container: {
+    maxWidth: '1200px',
+
+    '@mobile': {
+      maxWidth: '100%',
+      padding: '0 16px'
+    }
+  }
+}
+```
+
+## CLI Commands
+
+### build
+
+```
+npx esm-styles build [configPath]
+```
+
+Builds CSS files from JavaScript/TypeScript source files according to the configuration.
+
+#### Parameters
+
+- `configPath`: (Optional) Path to the configuration file. Defaults to `esm-styles.config.js` in the current directory.
+
+#### Process
+
+1. Loads the configuration file
+2. Processes each layer file
+3. Converts styles to CSS
+4. Generates theme/device variable files
+5. Creates supporting modules
+6. Outputs all files to the specified directory
+
+#### Example
+
+```bash
+# Use default config
+npx esm-styles build
+
+# Use custom config
+npx esm-styles build ./configs/my-esm-styles.config.js
+```

package/doc/css-variables.md

@@ -0,0 +1,32 @@
+# JS to CSS variables translation
+
+Source object:
+
+```js
+{
+  colors: {
+    paper: {
+      normal: '#212121',
+      tinted: '#323232',
+      bright: '#000000',
+    },
+    ink: {
+      normal: '#cccccc',
+      tinted: '#999999',
+      bright: { white: '#ffffff', yellow: '#ffff00' },
+    },
+  },
+}
+```
+
+Output CSS:
+
+```css
+--colors-paper-normal: #212121;
+--colors-paper-tinted: #323232;
+--colors-paper-bright: #000000;
+--colors-ink-normal: #cccccc;
+--colors-ink-tinted: #999999;
+--colors-ink-bright-white: #ffffff;
+--colors-ink-bright-yellow: #ffff00;
+```