gemcss 0.3.0 → 0.4.0

package/README.md

@@ -1,7 +1,7 @@
 # gemcss
 
 [![npm](https://img.shields.io/npm/v/gemcss.svg)](https://www.npmjs.com/package/gemcss)
-[![CI](https://github.com/vkalinichev/gemcss/actions/workflows/ci.yml/badge.svg)](https://github.com/vkalinichev/gemcss/actions/workflows/ci.yml)
+[![CI](https://img.shields.io/github/actions/workflow/status/vkalinichev/gemcss/ci.yml?branch=main&label=CI)](https://github.com/vkalinichev/gemcss/actions/workflows/ci.yml)
 
 Type-safe BEM classes from CSS modules. Write a plain `*.module.css` in BEM
 notation and get back an object where every block is a modifier-combinator

package/dist/cli/gen.d.ts

@@ -0,0 +1,17 @@
+/** Default pattern — every CSS module in the project. */
+export declare const DEFAULT_PATTERNS: string[];
+export interface RunOptions {
+    cwd?: string;
+}
+/** Declaration file name for a `*.module.css`.
+ * `x.module.css` -> `x.module.d.css.ts` (TS `allowArbitraryExtensions`). */
+export declare function dtsPathFor(cssFile: string): string;
+/** Generate the `.d.css.ts` next to one CSS file. Returns the declaration path. */
+export declare function generateOne(cssFile: string): Promise<string>;
+/** Remove the `.d.css.ts` of a CSS file (silent when it does not exist). */
+export declare function removeOne(cssFile: string): Promise<void>;
+/**
+ * Find CSS modules by pattern and generate a `.d.css.ts` for each one.
+ * Returns the paths of the written declarations.
+ */
+export declare function run(patterns: string[], opts?: RunOptions): Promise<string[]>;

package/dist/cli/gen.js

@@ -0,0 +1,39 @@
+import { glob, readFile, rm, writeFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { generateDts } from '../core/dts.js';
+import { parseCss } from '../core/parser.js';
+/** Default pattern — every CSS module in the project. */
+export const DEFAULT_PATTERNS = ['**/*.module.css'];
+/** Declaration file name for a `*.module.css`.
+ * `x.module.css` -> `x.module.d.css.ts` (TS `allowArbitraryExtensions`). */
+export function dtsPathFor(cssFile) {
+    return cssFile.replace(/\.css$/, '.d.css.ts');
+}
+/** Generate the `.d.css.ts` next to one CSS file. Returns the declaration path. */
+export async function generateOne(cssFile) {
+    const css = await readFile(cssFile, 'utf8');
+    const dts = generateDts(parseCss(css, { from: cssFile }));
+    const out = dtsPathFor(cssFile);
+    await writeFile(out, dts);
+    return out;
+}
+/** Remove the `.d.css.ts` of a CSS file (silent when it does not exist). */
+export async function removeOne(cssFile) {
+    await rm(dtsPathFor(cssFile), { force: true });
+}
+/**
+ * Find CSS modules by pattern and generate a `.d.css.ts` for each one.
+ * Returns the paths of the written declarations.
+ */
+export async function run(patterns, opts = {}) {
+    const cwd = opts.cwd ?? process.cwd();
+    const files = glob(patterns.length ? patterns : DEFAULT_PATTERNS, {
+        cwd,
+        exclude: ['**/node_modules/**'],
+    });
+    const written = [];
+    for await (const file of files) {
+        written.push(await generateOne(resolve(cwd, file)));
+    }
+    return written;
+}

package/dist/cli.d.ts

@@ -1 +1,2 @@
 #!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -1,78 +1,11 @@
 #!/usr/bin/env node
-import {
-  GemcssParseError,
-  parseCss
-} from "./chunk-CNXDOGPX.js";
-
-// src/cli.ts
-import { watch as fsWatch } from "fs";
-import { stat } from "fs/promises";
-import { resolve as resolve2 } from "path";
-import { parseArgs } from "util";
-
-// src/cli/gen.ts
-import { glob, readFile, rm, writeFile } from "fs/promises";
-import { resolve } from "path";
-
-// src/core/dts.ts
-var IDENT = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
-function propKey(name) {
-  return IDENT.test(name) ? name : JSON.stringify(name);
-}
-function strLit(value) {
-  return `'${value.replace(/\\/g, "\\\\").replace(/'/g, "\\'")}'`;
-}
-function propsParam(block) {
-  const keys = Object.keys(block.modifiers);
-  if (keys.length === 0) return "";
-  const fields = keys.map((k) => {
-    const mod = block.modifiers[k];
-    const type = mod.kind === "bool" ? "boolean" : mod.values.map(strLit).join(" | ");
-    return `${propKey(k)}?: ${type}`;
-  });
-  return `props?: { ${fields.join("; ")} }`;
-}
-function generateDts(module) {
-  const lines = ["declare const gems: {"];
-  for (const block of Object.values(module.blocks)) {
-    lines.push(`  ${propKey(block.name)}(${propsParam(block)}): string;`);
-  }
-  lines.push("};");
-  lines.push("export default gems;");
-  lines.push("");
-  return lines.join("\n");
-}
-
-// src/cli/gen.ts
-var DEFAULT_PATTERNS = ["**/*.module.css"];
-function dtsPathFor(cssFile) {
-  return cssFile.replace(/\.css$/, ".d.css.ts");
-}
-async function generateOne(cssFile) {
-  const css = await readFile(cssFile, "utf8");
-  const dts = generateDts(parseCss(css, { from: cssFile }));
-  const out = dtsPathFor(cssFile);
-  await writeFile(out, dts);
-  return out;
-}
-async function removeOne(cssFile) {
-  await rm(dtsPathFor(cssFile), { force: true });
-}
-async function run(patterns, opts = {}) {
-  const cwd = opts.cwd ?? process.cwd();
-  const files = glob(patterns.length ? patterns : DEFAULT_PATTERNS, {
-    cwd,
-    exclude: ["**/node_modules/**"]
-  });
-  const written = [];
-  for await (const file of files) {
-    written.push(await generateOne(resolve(cwd, file)));
-  }
-  return written;
-}
-
-// src/cli.ts
-var USAGE = `gemcss \u2014 generate .d.css.ts declarations for CSS modules
+import { watch as fsWatch } from 'node:fs';
+import { stat } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { parseArgs } from 'node:util';
+import { DEFAULT_PATTERNS, generateOne, removeOne, run } from './cli/gen.js';
+import { GemcssParseError } from './core/parser.js';
+const USAGE = `gemcss — generate .d.css.ts declarations for CSS modules
 
 Usage:
   gemcss [patterns...] [options]
@@ -82,56 +15,65 @@ Options:
   --cwd <dir>        working directory (default: process.cwd())
   -h, --help         show this help
 
-Default pattern: ${DEFAULT_PATTERNS.join(" ")}
+Default pattern: ${DEFAULT_PATTERNS.join(' ')}
 Watch mode follows every *.module.css under cwd (node_modules ignored).`;
 async function main() {
-  const { values, positionals } = parseArgs({
-    allowPositionals: true,
-    options: {
-      watch: { type: "boolean", short: "w" },
-      cwd: { type: "string" },
-      help: { type: "boolean", short: "h" }
+    const { values, positionals } = parseArgs({
+        allowPositionals: true,
+        options: {
+            watch: { type: 'boolean', short: 'w' },
+            cwd: { type: 'string' },
+            help: { type: 'boolean', short: 'h' },
+        },
+    });
+    if (values.help) {
+        console.log(USAGE);
+        return;
+    }
+    const cwd = resolve(values.cwd ?? process.cwd());
+    try {
+        const written = await run(positionals, { cwd });
+        for (const file of written)
+            console.log(`generated ${file}`);
+        console.log(`gemcss: ${written.length} file(s)`);
     }
-  });
-  if (values.help) {
-    console.log(USAGE);
-    return;
-  }
-  const cwd = resolve2(values.cwd ?? process.cwd());
-  try {
-    const written = await run(positionals, { cwd });
-    for (const file of written) console.log(`generated ${file}`);
-    console.log(`gemcss: ${written.length} file(s)`);
-  } catch (err) {
-    fail(err);
-    if (!values.watch) process.exit(1);
-  }
-  if (values.watch) watch(cwd);
+    catch (err) {
+        fail(err);
+        if (!values.watch)
+            process.exit(1);
+    }
+    if (values.watch)
+        watch(cwd);
 }
+/** Watch `*.module.css` under cwd: file exists — regenerate the declaration, gone — drop it. */
 function watch(cwd) {
-  fsWatch(cwd, { recursive: true }, (_event, rel) => {
-    if (!rel || !rel.endsWith(".module.css") || rel.includes("node_modules")) return;
-    void onChange(resolve2(cwd, rel));
-  });
-  console.log(`gemcss: watching ${cwd}`);
+    fsWatch(cwd, { recursive: true }, (_event, rel) => {
+        if (!rel || !rel.endsWith('.module.css') || rel.includes('node_modules'))
+            return;
+        void onChange(resolve(cwd, rel));
+    });
+    console.log(`gemcss: watching ${cwd}`);
 }
 async function onChange(file) {
-  try {
-    await stat(file);
-  } catch {
-    return removeOne(file);
-  }
-  try {
-    console.log(`generated ${await generateOne(file)}`);
-  } catch (err) {
-    fail(err);
-  }
+    try {
+        await stat(file);
+    }
+    catch {
+        return removeOne(file);
+    }
+    try {
+        console.log(`generated ${await generateOne(file)}`);
+    }
+    catch (err) {
+        fail(err);
+    }
 }
 function fail(err) {
-  if (err instanceof GemcssParseError) {
-    console.error(`gemcss: ${err.message}`);
-  } else {
-    console.error(err);
-  }
+    if (err instanceof GemcssParseError) {
+        console.error(`gemcss: ${err.message}`);
+    }
+    else {
+        console.error(err);
+    }
 }
 void main();

package/dist/core/compile.d.ts

@@ -0,0 +1,15 @@
+import type { Module } from './model.js';
+export interface CompileResult {
+    /** Transformed CSS with scoped class names — handed to the bundler for injection. */
+    css: string;
+    /** Map of raw name → scoped name (postcss-modules output). */
+    scoped: Record<string, string>;
+    /** The gemcss model built from the raw class names. */
+    module: Module;
+}
+export interface CompileOptions {
+    /** Scoped name template for postcss-modules. */
+    generateScopedName?: string;
+}
+/** Run a CSS module through postcss-modules and build the gemcss model. */
+export declare function compile(code: string, id: string, opts?: CompileOptions): Promise<CompileResult>;

package/dist/core/compile.js

@@ -0,0 +1,17 @@
+import postcss from 'postcss';
+import postcssModules from 'postcss-modules';
+import { parseCss } from './parser.js';
+/** Run a CSS module through postcss-modules and build the gemcss model. */
+export async function compile(code, id, opts = {}) {
+    let scoped = {};
+    const result = await postcss([
+        postcssModules({
+            generateScopedName: opts.generateScopedName ?? '[name]__[local]__[hash:base64:5]',
+            getJSON: (_file, json) => {
+                scoped = json;
+            },
+        }),
+    ]).process(code, { from: id });
+    const module = parseCss(code, { from: id });
+    return { css: result.css, scoped, module };
+}

package/dist/core/dts.d.ts

@@ -0,0 +1,6 @@
+import type { Module } from './model.js';
+/**
+ * Generate the `.d.ts` text for a model.
+ * Every block is a `(props?) => string` function; default export is `gems`.
+ */
+export declare function generateDts(module: Module): string;

package/dist/core/dts.js

@@ -0,0 +1,35 @@
+const IDENT = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+/** Property name: bare if a valid identifier, quoted otherwise. */
+function propKey(name) {
+    return IDENT.test(name) ? name : JSON.stringify(name);
+}
+/** TS string literal for an enum value. */
+function strLit(value) {
+    return `'${value.replace(/\\/g, '\\\\').replace(/'/g, "\\'")}'`;
+}
+/** Argument signature of a block's gem function (empty when it has no modifiers). */
+function propsParam(block) {
+    const keys = Object.keys(block.modifiers);
+    if (keys.length === 0)
+        return '';
+    const fields = keys.map((k) => {
+        const mod = block.modifiers[k];
+        const type = mod.kind === 'bool' ? 'boolean' : mod.values.map(strLit).join(' | ');
+        return `${propKey(k)}?: ${type}`;
+    });
+    return `props?: { ${fields.join('; ')} }`;
+}
+/**
+ * Generate the `.d.ts` text for a model.
+ * Every block is a `(props?) => string` function; default export is `gems`.
+ */
+export function generateDts(module) {
+    const lines = ['declare const gems: {'];
+    for (const block of Object.values(module.blocks)) {
+        lines.push(`  ${propKey(block.name)}(${propsParam(block)}): string;`);
+    }
+    lines.push('};');
+    lines.push('export default gems;');
+    lines.push('');
+    return lines.join('\n');
+}

package/dist/core/model.d.ts

@@ -0,0 +1,16 @@
+/** A single block modifier: either a boolean flag or an enum with a set of values. */
+export type Modifier = {
+    kind: 'bool';
+} | {
+    kind: 'enum';
+    values: string[];
+};
+/** A BEM block — the first segment of a class name. */
+export interface Block {
+    name: string;
+    modifiers: Record<string, Modifier>;
+}
+/** The model of one `*.module.css`. */
+export interface Module {
+    blocks: Record<string, Block>;
+}

package/dist/core/parser.d.ts

@@ -0,0 +1,17 @@
+import type { Module } from './model.js';
+/** Thrown when a class name violates the naming convention. */
+export declare class GemcssParseError extends Error {
+    constructor(message: string);
+}
+/**
+ * Extract class selectors from CSS source and build the model.
+ * Classes keep the order of their first appearance.
+ */
+export declare function parseCss(css: string, opts?: {
+    from?: string;
+}): Module;
+/**
+ * Build the model from a list of raw class names.
+ * Convention: `block`, `block_bool`, `block_key_value`.
+ */
+export declare function buildModule(classNames: string[], from?: string): Module;

package/dist/core/parser.js

@@ -0,0 +1,91 @@
+import postcss from 'postcss';
+import selectorParser from 'postcss-selector-parser';
+/** Thrown when a class name violates the naming convention. */
+export class GemcssParseError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'GemcssParseError';
+    }
+}
+function ctx(from) {
+    return from ? ` (in ${from})` : '';
+}
+/**
+ * Extract class selectors from CSS source and build the model.
+ * Classes keep the order of their first appearance.
+ */
+export function parseCss(css, opts = {}) {
+    const root = postcss.parse(css, { from: opts.from });
+    const classNames = [];
+    const seen = new Set();
+    root.walkRules((rule) => {
+        selectorParser((selectors) => {
+            selectors.walkClasses((cls) => {
+                if (!seen.has(cls.value)) {
+                    seen.add(cls.value);
+                    classNames.push(cls.value);
+                }
+            });
+        }).processSync(rule.selector);
+    });
+    return buildModule(classNames, opts.from);
+}
+/**
+ * Build the model from a list of raw class names.
+ * Convention: `block`, `block_bool`, `block_key_value`.
+ */
+export function buildModule(classNames, from) {
+    const blocks = {};
+    for (const raw of classNames) {
+        const segments = raw.split('_');
+        const blockName = segments[0];
+        if (!blockName) {
+            throw new GemcssParseError(`Empty block name in class ".${raw}"${ctx(from)}`);
+        }
+        const block = (blocks[blockName] ??= {
+            name: blockName,
+            modifiers: {},
+        });
+        const tail = segments.slice(1);
+        if (tail.length === 0)
+            continue;
+        if (tail.length === 1) {
+            const key = tail[0];
+            if (!key)
+                throw new GemcssParseError(`Empty modifier in class ".${raw}"${ctx(from)}`);
+            assignBool(block, key, raw, from);
+            continue;
+        }
+        if (tail.length === 2) {
+            const key = tail[0];
+            const value = tail[1];
+            if (!key || !value) {
+                throw new GemcssParseError(`Empty modifier key/value in class ".${raw}"${ctx(from)}`);
+            }
+            assignEnum(block, key, value, raw, from);
+            continue;
+        }
+        throw new GemcssParseError(`Class ".${raw}" has more than one modifier segment after block "${blockName}". ` +
+            `Allowed: block, block_bool, block_key_value.${ctx(from)}`);
+    }
+    return { blocks };
+}
+function assignBool(block, key, raw, from) {
+    const existing = block.modifiers[key];
+    if (existing && existing.kind === 'enum') {
+        throw new GemcssParseError(`Modifier "${key}" of block "${block.name}" used as both boolean (".${raw}") and enum.${ctx(from)}`);
+    }
+    block.modifiers[key] = { kind: 'bool' };
+}
+function assignEnum(block, key, value, raw, from) {
+    const existing = block.modifiers[key];
+    if (existing && existing.kind === 'bool') {
+        throw new GemcssParseError(`Modifier "${key}" of block "${block.name}" used as both enum (".${raw}") and boolean.${ctx(from)}`);
+    }
+    const mod = existing && existing.kind === 'enum'
+        ? existing
+        : (block.modifiers[key] = { kind: 'enum', values: [] });
+    if (!mod.values.includes(value)) {
+        mod.values.push(value);
+    }
+}

package/dist/core/runtime-path.d.ts

@@ -0,0 +1,3 @@
+/** Absolute path to the gemcss runtime: generated and virtual modules cannot
+ * resolve a bare specifier, so the emitted import gets a ready-made path. */
+export declare function runtimePath(): string;

package/dist/core/runtime-path.js

@@ -0,0 +1,6 @@
+import { createRequire } from 'node:module';
+/** Absolute path to the gemcss runtime: generated and virtual modules cannot
+ * resolve a bare specifier, so the emitted import gets a ready-made path. */
+export function runtimePath() {
+    return createRequire(import.meta.url).resolve('gemcss/runtime');
+}

package/dist/plugin/core/dts.d.ts

@@ -0,0 +1,6 @@
+import type { Module } from './model.js';
+/**
+ * Generate the `.d.ts` text for a model.
+ * Every block is a `(props?) => string` function; default export is `gems`.
+ */
+export declare function generateDts(module: Module): string;

package/dist/plugin/core/dts.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateDts = generateDts;
+const IDENT = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+/** Property name: bare if a valid identifier, quoted otherwise. */
+function propKey(name) {
+    return IDENT.test(name) ? name : JSON.stringify(name);
+}
+/** TS string literal for an enum value. */
+function strLit(value) {
+    return `'${value.replace(/\\/g, '\\\\').replace(/'/g, "\\'")}'`;
+}
+/** Argument signature of a block's gem function (empty when it has no modifiers). */
+function propsParam(block) {
+    const keys = Object.keys(block.modifiers);
+    if (keys.length === 0)
+        return '';
+    const fields = keys.map((k) => {
+        const mod = block.modifiers[k];
+        const type = mod.kind === 'bool' ? 'boolean' : mod.values.map(strLit).join(' | ');
+        return `${propKey(k)}?: ${type}`;
+    });
+    return `props?: { ${fields.join('; ')} }`;
+}
+/**
+ * Generate the `.d.ts` text for a model.
+ * Every block is a `(props?) => string` function; default export is `gems`.
+ */
+function generateDts(module) {
+    const lines = ['declare const gems: {'];
+    for (const block of Object.values(module.blocks)) {
+        lines.push(`  ${propKey(block.name)}(${propsParam(block)}): string;`);
+    }
+    lines.push('};');
+    lines.push('export default gems;');
+    lines.push('');
+    return lines.join('\n');
+}

package/dist/plugin/core/model.d.ts

@@ -0,0 +1,16 @@
+/** A single block modifier: either a boolean flag or an enum with a set of values. */
+export type Modifier = {
+    kind: 'bool';
+} | {
+    kind: 'enum';
+    values: string[];
+};
+/** A BEM block — the first segment of a class name. */
+export interface Block {
+    name: string;
+    modifiers: Record<string, Modifier>;
+}
+/** The model of one `*.module.css`. */
+export interface Module {
+    blocks: Record<string, Block>;
+}

package/dist/plugin/core/model.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/plugin/core/parser.d.ts

@@ -0,0 +1,17 @@
+import type { Module } from './model.js';
+/** Thrown when a class name violates the naming convention. */
+export declare class GemcssParseError extends Error {
+    constructor(message: string);
+}
+/**
+ * Extract class selectors from CSS source and build the model.
+ * Classes keep the order of their first appearance.
+ */
+export declare function parseCss(css: string, opts?: {
+    from?: string;
+}): Module;
+/**
+ * Build the model from a list of raw class names.
+ * Convention: `block`, `block_bool`, `block_key_value`.
+ */
+export declare function buildModule(classNames: string[], from?: string): Module;