@master/css-compiler 2.0.0-beta.99 → 2.0.0-rc.70

package/README.md

@@ -1,156 +1,57 @@
-<br>
-<div align="center">
-
-<p align="center">
-    <a href="https://css.master.co">
-        <picture>
-            <source media="(prefers-color-scheme: dark)" srcset="https://user-images.githubusercontent.com/33840671/201701649-3bb7d698-abec-4d5f-ac30-ccc4d7bafcd4.svg">
-            <source media="(prefers-color-scheme: light)" srcset="https://user-images.githubusercontent.com/33840671/201703010-77bf2373-9899-40cc-98f5-30cf9b546941.svg">
-            <img alt="Master CSS" src="https://user-images.githubusercontent.com/33840671/201703010-77bf2373-9899-40cc-98f5-30cf9b546941.svg" width="100%">
-        </picture>
-    </a>
-</p>
-<p align="center">The ahead-of-time compiler of Master CSS</p>
-
-<p align="center">
-    <a aria-label="overview" href="https://github.com/master-co/css/tree/beta">
-        <picture>
-            <source media="(prefers-color-scheme: dark)" srcset="https://img.shields.io/badge/%E2%AC%85%20back-%20?color=212022&style=for-the-badge">
-            <source media="(prefers-color-scheme: light)" srcset="https://img.shields.io/badge/%E2%AC%85%20back-%20?color=f6f7f8&style=for-the-badge">
-            <img alt="NPM Version" src="https://img.shields.io/badge/%E2%AC%85%20back-%20?color=f6f7f8&style=for-the-badge">
-        </picture>
-    </a>
-    <a aria-label="GitHub release (latest by date including pre-releases)" href="https://github.com/master-co/css/releases">
-        <picture>
-            <source media="(prefers-color-scheme: dark)" srcset="https://img.shields.io/github/v/release/master-co/css?include_prereleases&color=212022&label=&style=for-the-badge&logo=github&logoColor=fff">
-            <source media="(prefers-color-scheme: light)" srcset="https://img.shields.io/github/v/release/master-co/css?include_prereleases&color=f6f7f8&label=&style=for-the-badge&logo=github&logoColor=%23000">
-            <img alt="NPM Version" src="https://img.shields.io/github/v/release/master-co/css?include_prereleases&color=f6f7f8&label=&style=for-the-badge&logo=github">
-        </picture>
-    </a>
-    <a aria-label="NPM Package" href="https://www.npmjs.com/package/@master/css-compiler">
-        <picture>
-            <source media="(prefers-color-scheme: dark)" srcset="https://img.shields.io/npm/dm/@master/css-compiler?color=212022&label=%20&logo=npm&style=for-the-badge">
-            <source media="(prefers-color-scheme: light)" srcset="https://img.shields.io/npm/dm/@master/css-compiler?color=f6f7f8&label=%20&logo=npm&style=for-the-badge">
-            <img alt="NPM package ( download / month )" src="https://img.shields.io/npm/dm/@master/css-compiler?color=f6f7f8&label=%20&logo=npm&style=for-the-badge">
-        </picture>
-    </a>
-    <a aria-label="Discord Community" href="https://discord.gg/sZNKpAAAw6">
-        <picture>
-            <source media="(prefers-color-scheme: dark)" srcset="https://img.shields.io/discord/917780624314613760?color=212022&label=%20&logo=discord&style=for-the-badge">
-            <source media="(prefers-color-scheme: light)" srcset="https://img.shields.io/discord/917780624314613760?color=f6f7f8&label=%20&logo=discord&style=for-the-badge">
-            <img alt="Discord online" src="https://img.shields.io/discord/917780624314613760?color=f6f7f8&label=%20&logo=discord&style=for-the-badge">
-        </picture>
-    </a>
-    <a aria-label="Follow @mastercorg" href="https://twitter.com/mastercorg">
-        <picture>
-            <source media="(prefers-color-scheme: dark)" srcset="https://img.shields.io/static/v1?label=%20&message=twitter&color=212022&logo=twitter&style=for-the-badge">
-            <source media="(prefers-color-scheme: light)" srcset="https://img.shields.io/static/v1?label=%20&message=twitter&color=f6f7f8&logo=twitter&style=for-the-badge">
-            <img alt="Follow @mastercorg" src="https://img.shields.io/static/v1?label=%20&message=twitter&color=f6f7f8&logo=twitter&style=for-the-badge">
-        </picture>
-    </a>
-    <a aria-label="Github Actions" href="https://github.com/1aron/repo/actions/workflows/release.yml">
-        <picture>
-            <source media="(prefers-color-scheme: dark)" srcset="https://img.shields.io/github/actions/workflow/status/master-co/css/release.yml?branch=beta&label=%20&message=twitter&color=212022&logo=githubactions&style=for-the-badge">
-            <source media="(prefers-color-scheme: light)" srcset="https://img.shields.io/github/actions/workflow/status/master-co/css/release.yml?branch=beta&label=%20&message=twitter&color=f6f7f8&logo=githubactions&style=for-the-badge&logoColor=%23000">
-            <img alt="Github release actions" src="https://img.shields.io/github/actions/workflow/status/master-co/css/release.yml?branch=beta&label=%20&message=twitter&color=f6f7f8&logo=githubactions&style=for-the-badge&logoColor=%23000">
-        </picture>
-    </a>
-</p>
-
-</div>
-
-## Usage
+# @master/css-compiler
+
+Compile Master CSS stylesheet directives into manifest data, native CSS, and directive metadata.
+
+## Installation
+
 ```bash
 npm install @master/css-compiler
 ```
 
-```ts
-const compiler = await new MasterCSSCompiler().init()
-```
+## Responsibility
 
-## Options
-```ts
-{
-    // specify virtual CSS module id (e.g. virtual:master.css)
-    module: 'master.css',
-    // specify config file path or set `Config`
-    config: 'master.css.{ts,js,mjs,cjs}',
-    // forcibly specify sources for scanning, not excluded by `options.exclude`
-    sources: [],
-    // specify sources for scanning
-    include: ['**/*.{html,js,jsx,ts,tsx,svelte,astro,vue,md,mdx,pug,php}'],
-    // specify sources to exclude
-    exclude: [
-        '**/node_modules/**',
-        '**/*.d.ts',
-        '**/*.test.*',
-        'node_modules',
-        'master.css.{js,ts,mjs,cjs}',
-        'dist',
-        'out',
-        'README.md'
-    ],
-    // whitelist of class names for unpredictable dynamics
-    fixedClasses: [],
-    // blacklist of class names to exclude accidentally captured
-    ignoredClasses: [], // or RegExp[]
-    cwd: process.cwd()
-}
-```
+`@master/css-compiler` is the CSS source compiler for Master CSS. It parses CSS manifest directives such as `@settings`, `@theme`, `@custom-variant`, `@defaults`, `@components`, `@utilities`, local `@compose`, top-level extraction directives, native CSS, and CSS import graphs.
 
-## Methods
+The compiler delegates class semantics and rule generation to `@master/css-engine`; project entry discovery belongs to `@master/css-project`.
 
-```ts
-// Initialize the compiler and MasterCSS
-init(): this
-```
+## API
 
-```ts
-// Scan sources, extract class names, and generate CSS rules
-compile()
-```
+### Root entry
 
-```ts
-// Extract potential class names from the given file content
-extract(name: string, content: string): string[]
-```
+Use the root entry in Node environments when CSS imports and filesystem dependencies should be resolved.
 
 ```ts
-// `extract(name, content)`, insert extractions, and generate CSS rules
-insert(name: string, content: string): boolean
+import {
+    compileCSS,
+    compileCSSFile,
+    compileCSSManifest,
+    compileCSSManifestFile,
+    compileProjectManifest,
+} from '@master/css-compiler'
 ```
 
-```ts
-// Read file source paths by `options.include` and `options.exclude`
-get sources(): string[]
-```
+Common flows:
 
 ```ts
-// Check source file path by `options.include` and `options.exclude`
-checkSourcePath(name: string): boolean
+const result = compileCSSManifest('@theme { --color-primary: #4f46e5; }')
+const fileResult = await compileCSSManifestFile('/project/src/index.css')
+const projectResult = await compileProjectManifest(['/project/src/index.css'])
 ```
 
-```ts
-// Read user config file by `options.config`
-readConfig(): Config
-```
+Compiler results include the compiled manifest, dependency paths, warnings, native CSS, and directive metadata used by build integrations.
 
-```ts
-// Get user config path
-get configPath(): string
-```
+### Browser entry
+
+Use `@master/css-compiler/browser` when CSS import resolution is not needed.
 
 ```ts
-// Get resolved user config path
-get resolvedConfigPath(): string
+import { compileCSSManifest } from '@master/css-compiler/browser'
 ```
 
-## Properties
+The browser compiler rejects `@reference` directives because they require filesystem resolution.
 
-```ts
-export default class MasterCSSCompiler {
-    css: MasterCSS
-    extractions = new Set<string>()
-    ...
-}
-```
+## Related packages
+
+- `@master/css-engine` executes compiled manifests.
+- `@master/css-project` discovers and loads project CSS manifest entries.
+- `@master/css-stylesheet` composes stylesheet entries for static rendering.

package/dist/browser.d.ts

@@ -0,0 +1,22 @@
+import init from 'lightningcss-wasm';
+import type { MasterCSSManifest } from '@master/css-schema/manifest';
+import { type CompileCSSOptions, type CompileCSSResult } from './core';
+export type * from './core';
+export type CompileCSSManifestSourceOptions = CompileCSSOptions & {
+    baseManifest?: MasterCSSManifest;
+};
+export interface CompileCSSManifestResult extends Omit<CompileCSSResult, 'manifestInput'> {
+    manifest: MasterCSSManifest;
+    directives: CompileCSSResult;
+}
+export declare function initCSSCompiler(input?: Parameters<typeof init>[0]): Promise<void>;
+export declare function compileCSS(source: string, options?: CompileCSSOptions): Promise<CompileCSSResult>;
+export declare function compileCSSManifest(source: string, options?: CompileCSSManifestSourceOptions): Promise<CompileCSSManifestResult>;
+export declare function parseDirectives(source: string, options?: CompileCSSOptions): Promise<{
+    styleDefinitions?: import("~/packages/schema/src/css-directives").CSSDirectiveStyleDefinition[] | undefined;
+    manifestInput: import("~/packages/schema/src/css-directives").CSSDirectiveManifestInput;
+    extractionPolicy: import("~/packages/schema/src/css-directives").CSSDirectiveExtractionPolicy;
+    classNames: string[];
+    nativeClassNames: string[];
+    warnings: string[];
+}>;

package/dist/browser.mjs

@@ -0,0 +1,47 @@
+import init, { transform } from 'lightningcss-wasm';
+import { compileCSS as compileCSS$1, parseDirectives as parseDirectives$1 } from './core.mjs';
+import lowerCSSDirectives from './lower-css-directives.mjs';
+import { setCSSTransform } from './css-transform.mjs';
+
+let initPromise;
+async function initCSSCompiler(input) {
+    initPromise ??= init(input).then(()=>{
+        setCSSTransform(transform);
+    });
+    await initPromise;
+}
+async function compileCSS(source, options = {}) {
+    await initCSSCompiler();
+    return compileCSS$1(source, options);
+}
+async function compileCSSManifest(source, options = {}) {
+    const result = await compileCSS(source, options);
+    if (result.references?.length) {
+        throw new Error('Browser compileCSSManifest cannot resolve @reference directives. Inline referenced CSS or compile the stylesheet in a Node environment.');
+    }
+    const { manifestInput: _manifestInput, ...directiveData } = result;
+    const lowerResult = lowerCSSDirectives(result, {
+        baseManifest: options.baseManifest,
+        onWarning: options.onWarning
+    });
+    const generatedCSS = lowerResult.generatedCSS || '';
+    const css = [
+        result.nativeCSS,
+        generatedCSS
+    ].filter(Boolean).join('\n');
+    return {
+        ...directiveData,
+        dependencies: [],
+        manifest: lowerResult.manifest,
+        warnings: lowerResult.warnings,
+        generatedCSS,
+        css,
+        directives: result
+    };
+}
+async function parseDirectives(source, options = {}) {
+    await initCSSCompiler();
+    return parseDirectives$1(source, options);
+}
+
+export { compileCSS, compileCSSManifest, initCSSCompiler, parseDirectives };

package/dist/core.d.ts

@@ -0,0 +1,48 @@
+import { type CSSDirectiveManifestInput, type CSSDirectiveReference, type CSSDirectiveResult, type CSSDirectiveStyleDefinition } from '@master/css-schema/css-directives';
+import { setCSSTransform, type CSSTransform } from './css-transform';
+import { createSourceLocationResolver, type CSSDirectiveRuleRange } from '@master/css-lexer';
+import { collectStandaloneCSSDirectiveExtractionPolicy, createCSSDirectiveExtractionPolicy, findStandaloneCSSDirectiveStatements, findStandaloneMasterDirectiveStatements, mergeCSSDirectiveExtractionPolicy, removeStandaloneCSSDirectives, removeStandaloneMasterDirectives, type StandaloneCSSDirectiveStatement, type StandaloneMasterDirectiveStatement } from './lexer/standalone-master';
+export { collectStandaloneCSSDirectiveExtractionPolicy, createCSSDirectiveExtractionPolicy, findStandaloneCSSDirectiveStatements, findStandaloneMasterDirectiveStatements, mergeCSSDirectiveExtractionPolicy, removeStandaloneCSSDirectives, removeStandaloneMasterDirectives, setCSSTransform };
+export type { CSSTransform, StandaloneCSSDirectiveStatement, StandaloneMasterDirectiveStatement };
+export interface CompileCSSOptions {
+    classes?: string[];
+    from?: string;
+    preserveNativeCSS?: boolean;
+    onWarning?: (warning: string) => void;
+}
+export interface CompileCSSFileOptions extends CompileCSSOptions {
+    root?: string;
+}
+export type CompileCSSResult = CSSDirectiveResult;
+export interface ResolvedCSSImportGraph {
+    source: string;
+    dependencies: string[];
+    references?: CSSDirectiveReference[];
+}
+type ParsedStyleDefinition = CSSDirectiveStyleDefinition;
+export interface ParsedDirectives extends Pick<CompileCSSResult, 'manifestInput' | 'extractionPolicy' | 'classNames' | 'nativeClassNames' | 'warnings'> {
+    styleDefinitions?: ParsedStyleDefinition[];
+    styleOrder?: number;
+    source?: string;
+    filename?: string;
+    composeRanges?: CSSDirectiveRuleRange[];
+    composeRangeIndex?: number;
+    sourceLocationResolver?: ReturnType<typeof createSourceLocationResolver>;
+}
+export interface CSSReferenceStatement extends CSSDirectiveReference {
+    start: number;
+    end: number;
+    statement: string;
+}
+export declare function findCSSReferenceStatements(source: string, filename?: string): CSSReferenceStatement[];
+export declare function removeCSSReferenceStatements(source: string, filename?: string): string;
+export declare function maskManagedPatternEntryNames(source: string): string;
+export declare function compileCSS(source: string, options?: CompileCSSOptions): CompileCSSResult;
+export declare function parseDirectives(source: string, options?: CompileCSSOptions): {
+    styleDefinitions?: CSSDirectiveStyleDefinition[] | undefined;
+    manifestInput: CSSDirectiveManifestInput;
+    extractionPolicy: import("@master/css-schema/css-directives").CSSDirectiveExtractionPolicy;
+    classNames: string[];
+    nativeClassNames: string[];
+    warnings: string[];
+};