@pre.style/core 3.0.0-alpha.0 → 3.1.0-alpha.0

package/README.md

@@ -88,6 +88,8 @@ export function Card({ children }) {
 
 In a build, the plugin writes `pre.style.css` to your output directory and links it from `index.html`. In dev, the CSS is served by Vite and updates as you edit.
 
+You can also write styles in `.css` and `.scss` files and import their classes, like CSS Modules. See [Stylesheet files](#stylesheet-files).
+
 ### Frameworks without `index.html`
 
 Frameworks that render on the server, such as React Router's framework mode, don't use `index.html`. Import pre.style's CSS in your root module instead:
@@ -179,6 +181,20 @@ css`
 `;
 ```
 
+### `composes` in blocks
+
+A block can build on classes from a [stylesheet file](#stylesheet-files), or on global class names, with `composes`, as in CSS Modules:
+
+```js
+css`
+  composes: button from './button.css';
+  composes: legacy-btn from global;
+  color: white;
+`;
+```
+
+The block's class string then includes the composed classes, and its own declarations replace the composed ones they conflict with, as `cn` would. `composes` must come before the block's other declarations, and can't be used inside nested selectors or at-rules.
+
 ### In HTML
 
 HTML can't import anything, so blocks in HTML files that Vite processes, such as `index.html`, are found by matching `` css` `` and `` scss` ``:
@@ -213,20 +229,140 @@ When every argument is a block or a string literal, the plugin resolves the call
 
 > **Note:** `cn` removes `!important` declarations too. A later class that sets the same property wins, even when the earlier one is `!important`.
 
-## Sharing values with prepended files
+## Stylesheet files
+
+Styles can also live in `.css` and `.scss` files, imported with the `pre.style` import attribute. Each class in the file is exported with its class string, like [CSS Modules](https://github.com/css-modules/css-modules):
+
+```css
+/* button.css */
+.button {
+  background-color: #0071ba;
+  color: white;
+
+  &:hover {
+    background-color: #005a94;
+  }
+}
+
+.primary-button {
+  composes: button;
+  font-weight: 600;
+}
+```
+
+```jsx
+import { button, 'primary-button' as primaryButton } from './button.css' with { type: 'pre.style' };
+
+<button className={primaryButton}>Save</button>;
+```
+
+`.css` files are compiled like `css` blocks, and `.scss` files like `scss` blocks, into the same atomic classes and the same CSS file. Each export is a plain string constant, so bundlers drop the ones you don't use. A class that isn't a valid identifier (`primary-button`) is exported by its string name, so import it with `as`. Only imports with `with { type: 'pre.style' }` are compiled this way; plain `import './global.css'` and `.module.css` imports work as usual. Your `tsconfig.json` needs `"module"` set to `"esnext"`, `"preserve"`, or a `"node*"` setting for TypeScript to allow the attribute.
+
+How a file becomes classes:
 
-Use `prependFiles` to add files to the start of every block, for custom properties, SCSS variables, mixins, and so on. Each file is read once per build.
+- **Each class is a block.** A class's rules, wherever they are in the file, are compiled as one block with the class replaced by `&`. `.button:hover` is `&:hover`, `@media (…) { .button { … } }` is an at-rule class of `button`, and a later rule for the class overrides an earlier one, as in plain CSS.
+- **A selector belongs to the class it styles:** the first class in the rightmost part of the selector that has one. `.card .title` belongs to `title`, and `.list > li` to `list` (as `& > li`).
+- **Selector lists** (`.a, .b { … }`) apply the declarations to each class.
+- **Rules without a class,** such as `:root`, `body`, `@keyframes`, and `@font-face`, are written to the CSS file as they are. So are `@import` rules, as in blocks.
+- **Empty classes** (`.empty {}`) are exported as `''`.
+- **Everything is global.** There's no `:global()` or `:local()`. Classes that aren't exported from the file, such as `.dark` in `.dark .button`, are written as they are, so you add them to elements yourself.
+- **Classes from prepended files aren't exported.** Their rules are written as they are.
+- **Every class in an imported file is written to the CSS file,** even the ones you don't use, as with CSS Modules.
+
+In `.scss` files, relative `@use`, `@forward`, and `@import` resolve from the file, and [prepended files](#sharing-values-with-prepended-files) work as they do in blocks. Classes a prepended mixin writes into the file are the file's own.
+
+### Classes used as context
+
+Atomic classes are shared, so no single class in a class string identifies one export. When an exported class is used as context for another, as `card` is in `.card:hover .title`, pre.style gives it a **marker**: one extra class, added to `card`'s class string, that the selector uses.
+
+```css
+.card { padding-top: 1rem; }
+.title { color: black; }
+.card:hover .title { color: red; }
+```
+
+```css
+.D{padding-top:1rem}
+.C{color:#000}
+.A:hover .B{color:red}
+```
+
+`card` is `"D A"`, where `A` is its marker, and `title` is `"C B"`.
+
+> [!IMPORTANT]
+> **Watch out for compound selectors.** In `.a.b { … }`, the first class, `a`, gets the declarations, and `b` becomes a marker. `b`'s export is only its marker, so `b` on its own applies none of those styles: they apply to elements with both `a` and `b`. Prefer separate classes, or a selector variant on one class (`.a { &.is-open { … } }`), when you can.
+
+### `composes` in stylesheet files
+
+`composes` works as in CSS Modules:
+
+```css
+.base { color: gray; padding: 1rem; }
+.primary { composes: base; color: blue; }
+.wide { composes: card from './card.css'; }
+.legacy { composes: old-btn from global; }
+```
+
+> [!IMPORTANT]
+> **`composes` resolves conflicts, unlike CSS Modules.** CSS Modules only joins class names. pre.style resolves `composes` like `cn(composed, own)`: the class's own declarations replace the composed ones they conflict with, and those are dropped from the class string. Above, `primary` has `color: blue` and not `color: gray`. As in CSS Modules, `composes` must come before the rule's other declarations, can't be used in nested selectors or at-rules, and fails the build if classes compose each other in a cycle.
+
+Classes composed `from global` are added to the class string as they are. Composed classes keep their markers.
+
+### Using exports with `cn`
+
+Stylesheet exports are plain class strings, so they work with `cn`. Calls whose arguments are all blocks, string literals, or stylesheet exports (named imports, or members of a namespace import such as `styles.button`) are resolved during the build.
+
+### Types
+
+TypeScript 7.1 adds [content mappers](https://devblogs.microsoft.com/typescript/announcing-typescript-7-1-beta/), which `@pre.style/core` provides, so named imports are typed with each file's exact classes. Register it in `tsconfig.json`:
+
+```json
+{
+  "contentMappers": [{ "package": "@pre.style/core", "extensions": [".css", ".scss"] }]
+}
+```
+
+Content mappers run code from a package, so `tsc` needs the `--runExternalCode` flag, and editors need the workspace to be trusted. Mappers are chosen by file extension, so every `.css` and `.scss` file in the program gets pre.style's types, including ones imported without the attribute.
+
+Before TypeScript 7.1, add this declaration to your project instead (for example as `src/stylesheets.d.ts`):
 
 ```ts
-preStyle({
-  prependFiles: {
-    css: ['src/styles/tokens.css'],
-    scss: ['src/styles/_variables.scss', 'src/styles/_mixins.scss'],
-  },
-});
+declare module '*.css' {
+  const classes: { readonly [name: string]: string };
+  export = classes;
+}
+declare module '*.scss' {
+  const classes: { readonly [name: string]: string };
+  export = classes;
+}
+```
+
+TypeScript can't type named imports from it, so use a namespace import:
+
+```ts
+import * as styles from './button.css' with { type: 'pre.style' };
+
+styles.button;
+```
+
+Namespace imports still let bundlers drop the classes you don't use. **Remove the declaration when you register the content mapper:** TypeScript prefers it over the mapper.
+
+## Sharing values with prepended files
+
+Use `prependFiles`, in the `pre.style` field of your `package.json`, to add files to the start of every block and stylesheet file, for custom properties, SCSS variables, mixins, and so on. Each file is read once per build.
+
+```json
+{
+  "pre.style": {
+    "prependFiles": {
+      "css": ["src/styles/tokens.css"],
+      "scss": ["src/styles/_variables.scss", "src/styles/_mixins.scss"]
+    }
+  }
+}
 ```
 
-An array applies the files to every block. An object applies `css` files only to `css` blocks, and `scss` files only to `scss` blocks.
+An array applies the files to every block. An object applies `css` files only to `css` blocks and `.css` files, and `scss` files only to `scss` blocks and `.scss` files. Paths are relative to the `package.json`.
 
 Rules the files output, such as `:root { --space: 4px }`, appear in the CSS file once. Keep prepended files to things that don't output CSS, or output it once (variables, mixins, custom properties). Large libraries slow the build down.
 
@@ -238,15 +374,17 @@ A component library styled with pre.style ships its blocks uncompiled, and each
 
 Install it. The plugin finds dependencies with a `pre.style` field in their `package.json` (and the libraries those depend on) and compiles them. There's nothing to configure.
 
-To compile a package that doesn't have the field, or to change how one is compiled, use the `libraries` option. `false` leaves a package out.
+To compile a package that doesn't have the field, or to change how one is compiled, use the `libraries` setting in your `package.json`'s `pre.style` field. `true` uses the defaults, and `false` leaves a package out.
 
-```ts
-preStyle({
-  libraries: {
-    'legacy-ui': { include: 'dist/**/*.js' },
-    'some-ui': false,
-  },
-});
+```json
+{
+  "pre.style": {
+    "libraries": {
+      "legacy-ui": { "include": "dist/**/*.js" },
+      "some-ui": false
+    }
+  }
+}
 ```
 
 A library's class names depend on the whole app, so they differ between apps. Don't depend on them.
@@ -275,10 +413,11 @@ A library's class names depend on the whole app, so they differ between apps. Do
 
 | Field          | Default                      | Description |
 | -------------- | ---------------------------- | ----------- |
-| `include`      | Every JS, TS, and Astro file | Globs of the files with blocks, relative to the package. |
-| `prependFiles` |                              | Files added to the start of the library's blocks, relative to the package. They apply only to the library's blocks, not the app's, so the library's tokens and mixins are always available to it and never leak into the app. |
+| `include`      | Every JS, TS, and Astro file | Globs of the files with blocks, relative to the package. A glob or an array of them. Stylesheet files the library imports are found from its imports. |
+| `exclude`      |                              | Globs removed from `include`. |
+| `prependFiles` |                              | Files added to the start of the library's blocks and stylesheet files, relative to the package. They apply only to the library's, not the app's, so the library's tokens and mixins are always available to it and never leak into the app. |
 
-`"pre.style": true` uses the defaults.
+`"pre.style": true` uses the defaults. A library's field uses the same name and shape as an app's (see [Configuration](#configuration)). `libraries` and `quirksMode` only apply to the app, so in a library's field they're ignored, with a warning. A package that is both, such as a library with its own demo app, is read as the app when it's the Vite root, and as a library when it's a dependency.
 
 To let apps use the library's tokens in their own blocks, export the token files, and apps can add them to their own `prependFiles`.
 
@@ -338,12 +477,52 @@ Utility-first frameworks such as [Tailwind CSS](https://tailwindcss.com/) also p
 
 ## Configuration
 
-All options are optional.
+Options live in one of two places. Each option is set in exactly one of them.
+
+### In `package.json`
+
+Options every tool that reads your styles has to agree on (the bundler plugin, and TypeScript's [content mapper](#types)) go in a `pre.style` field in your app's `package.json`. The plugin reads the `package.json` nearest Vite's root, and paths in it are relative to that file. All options are optional.
+
+```json
+{
+  "pre.style": {
+    "include": ["src/**/*.{ts,tsx}", "index.html"],
+    "prependFiles": ["src/styles/tokens.css"]
+  }
+}
+```
+
+| Option         | Default                                           | Description |
+| -------------- | ------------------------------------------------- | ----------- |
+| `include`      | `**/*.{js,jsx,ts,tsx,mjs,cjs,mts,cts,html,astro}` | Globs of the files with blocks, relative to the `package.json`. A glob or an array of them. Scanned before a build to assign names; stylesheet files are found from the scanned files' imports. `node_modules` and the output directory are always skipped. |
+| `exclude`      |                                                   | Globs removed from `include`. |
+| `prependFiles` |                                                   | Files added to the start of the app's blocks and stylesheet files. See [Sharing values with prepended files](#sharing-values-with-prepended-files). |
+| `libraries`    |                                                   | Component libraries to compile, by package name, in addition to dependencies with a `pre.style` field. A config replaces the package's field, `true` uses the defaults, and `false` leaves the package out. See [Component libraries](#component-libraries). |
+| `quirksMode`   | `false`                                           | **You probably don't want this.** Use lowercase class names only, for pages in quirks mode. Names get longer. See [Quirks mode](#quirks-mode). |
+
+The plugin warns about keys it doesn't know, and fails the build on values of the wrong type. For completion and validation in your editor, `@pre.style/core` includes a JSON Schema for the field, at `node_modules/@pre.style/core/package.schema.json`. In VS Code, add it to your settings:
+
+```json
+{
+  "json.schemas": [
+    {
+      "fileMatch": ["package.json"],
+      "schema": {
+        "properties": {
+          "pre.style": { "$ref": "./node_modules/@pre.style/core/package.schema.json" }
+        }
+      }
+    }
+  ]
+}
+```
+
+### Plugin options
+
+Options about how a build writes its output go to the plugin. All options are optional.
 
 ```ts
 preStyle({
-  include: ['src/**/*.{ts,tsx}', 'index.html'],
-  prependFiles: ['src/styles/tokens.css'],
   lightningcss: { minify: true, targets: { safari: 16 << 16 } },
   sourceMap: true,
   quotes: 'single-quote',
@@ -356,13 +535,8 @@ preStyle({
 
 | Option         | Default                                           | Description |
 | -------------- | ------------------------------------------------- | ----------- |
-| `include`      | `**/*.{js,jsx,ts,tsx,mjs,cjs,mts,cts,html,astro}` | Globs of the files with blocks, relative to Vite's root. Scanned before a build to assign names. `node_modules` and the output directory are always skipped. |
-| `exclude`      |                                                   | Globs removed from `include`. |
-| `prependFiles` |                                                   | Files added to the start of the app's blocks. See [Sharing values with prepended files](#sharing-values-with-prepended-files). |
-| `libraries`    |                                                   | Component libraries to compile, by package name, in addition to dependencies with a `pre.style` field. A config replaces the package's field, and `false` leaves the package out. See [Component libraries](#component-libraries). |
 | `lightningcss` |                                                   | [Lightning CSS options](https://lightningcss.dev/transforms.html), such as `minify`, `targets`, `drafts`, and `visitor`. A `visitor` runs before pre.style processes each block. `filename`, `code`, `sourceMap`, `projectRoot`, `inputSourceMap`, and `cssModules` are ignored. |
 | `sourceMap`    | `false`                                           | Generate a source map for the CSS, mapping each class to the first block it appears in. In dev, it's shown in the browser (the plugin turns on Vite's `css.devSourcemap`). In builds, it's written next to `output.file`. When you import `virtual:pre.style.css`, builds have no CSS source map, because Vite doesn't write them for bundled CSS. |
-| `quirksMode`   | `false`                                           | **You probably don't want this.** Use lowercase class names only, for pages in quirks mode. Names get longer. See [Quirks mode](#quirks-mode). |
 | `quotes`       | `'double-quote'`                                  | Quotes around the class string that replaces each block in JS: `'single-quote'`, `'double-quote'`, or `'backtick'`. |
 | `output.file`  | `'pre.style.css'`                                  | Path and name of the CSS file, relative to Vite's `build.outDir`. |
 | `output.banner`|                                                   | Text added to the start of the CSS file. |
@@ -370,6 +544,8 @@ preStyle({
 
 The CSS isn't minified unless you set `lightningcss: { minify: true }`.
 
+Before 3.1, `include`, `exclude`, `prependFiles`, `libraries`, and `quirksMode` were plugin options. Passing them to the plugin now fails with a message pointing to `package.json`.
+
 ### Quirks mode
 
 > [!WARNING]
@@ -377,7 +553,7 @@ The CSS isn't minified unless you set `lightningcss: { minify: true }`.
 
 Pages without a doctype render in quirks mode, where class selectors ignore case. pre.style uses both uppercase and lowercase letters in class names, so `.A` and `.a` would apply to each other's elements. Add `<!doctype html>` to fix this. The plugin warns during the build when an HTML file it processes has no doctype.
 
-If you can't add one, for example because your CSS is loaded into a page you don't control, set `quirksMode: true`. Class names then use only lowercase letters, digits, `-`, and `_`. That leaves 27 one-character names instead of 53, and about 1,050 two-character names instead of 3,445, so names get longer once a project has more than about 27 classes.
+If you can't add one, for example because your CSS is loaded into a page you don't control, set `"quirksMode": true` in your `package.json`'s `pre.style` field. Class names then use only lowercase letters, digits, `-`, and `_`. That leaves 27 one-character names instead of 53, and about 1,050 two-character names instead of 3,445, so names get longer once a project has more than about 27 classes.
 
 ## TypeScript
 
@@ -385,6 +561,8 @@ If you can't add one, for example because your CSS is loaded into a page you don
 
 `css` and `scss` must be used as tagged templates (`` css`…` ``), and every block must be compiled by the plugin. If code that uses them runs without the plugin, for example in tests run directly in Node, they throw an error saying the transform wasn't applied, instead of silently rendering unstyled.
 
+For stylesheet files, see [Types](#types).
+
 ## Errors
 
 The build fails, with the file, line, and column, when:
@@ -393,7 +571,9 @@ The build fails, with the file, line, and column, when:
 - Sass fails to compile an `scss` block;
 - a block contains `${…}` interpolation;
 - `css` or `scss` is used other than as a tagged template;
-- a project has an `scss` block but Sass isn't installed.
+- a project has an `scss` block or file but Sass isn't installed;
+- a stylesheet file has invalid CSS, or fails to compile with Sass;
+- `composes` comes after other declarations, is used in a nested selector or at-rule, names a class or file that doesn't exist, or forms a cycle.
 
 ## Known limitations
 
@@ -403,14 +583,17 @@ The build fails, with the file, line, and column, when:
 - Blocks in PHP and other templates aren't supported, because Vite doesn't output them.
 - Component libraries are found among the app's dependencies and the dependencies of other libraries. A library used only through a package that isn't one (a wrapper without a `pre.style` field) isn't found automatically; add it with the `libraries` option.
 - Before a build, Astro components are scanned like HTML, by matching `` css` `` and `` scss` ``. In a component that imports from `@pre.style/core`, text that only looks like a block, such as a code sample, is compiled too, and fails the build if it isn't valid CSS.
-- Positions in `scss` blocks point to the start of the block, since Sass's output doesn't match the original lines.
+- Positions in `scss` blocks point to the start of the block, since Sass's output doesn't match the original lines. In `.scss` files, Sass errors have positions, but source maps don't.
+- In `.scss` files, rules from modules loaded with `@use` are written as they are, like prepended files' rules, and their classes aren't exported: Sass writes them before the file's own rules.
+- Stylesheet imports must be static strings (`import`, `export … from`, and `import('./file.css', { with: { type: 'pre.style' } })`), and can't have a query.
+- TypeScript's content mapper handles every `.css` and `.scss` file in the program, since mappers are chosen by extension. A project that also imports Vite's `.module.css` files without the attribute gets pre.style's types for them.
 - Pages need a doctype (`<!doctype html>`). Without one, browsers use quirks mode, where class selectors ignore case, so classes like `.A` and `.a` would apply to each other's elements. See [Quirks mode](#quirks-mode).
 
 ## Packages
 
 | Package                 | Description                                            |
 | ----------------------- | ------------------------------------------------------ |
-| `@pre.style/core`             | `css`, `scss`, and `cn`, plus the compiler at `@pre.style/core/compiler` for bundler plugins. |
+| `@pre.style/core`             | `css`, `scss`, and `cn`, the compiler at `@pre.style/core/compiler` for bundler plugins, TypeScript's content mapper for stylesheet files, and the JSON Schema for the `package.json` field. |
 | `@pre.style/vite` | The Vite plugin.                                       |
 
 ## Development
@@ -435,7 +618,7 @@ npm run format     # Oxfmt
 npm run build
 ```
 
-`demo/` has three apps for trying pre.style on the client and server: a React Router app in framework mode (`react/react-router`), a TanStack Start app (`react/tanstack-start`), and an Astro app with React islands (`astro`). They have the same pages, and share a small React component library (`react/ui`), which ships its source with the blocks still in it and its design tokens, for each app's pre.style plugin to compile. The demos use the packages' TypeScript source, so changes to them show up without a build.
+`demo/` has three apps for trying pre.style on the client and server: a React Router app in framework mode (`react/react-router`), a TanStack Start app (`react/tanstack-start`), and an Astro app with React islands (`astro`). They have the same pages, and share a small React component library (`react/ui`), which ships its source with the blocks still in it (and a component styled from a `.scss` stylesheet file) and its design tokens, for each app's pre.style plugin to compile. The demos use the packages' TypeScript source, so changes to them show up without a build.
 
 ```sh
 npm run demo:react-router          # dev server

package/dist/compiler/block.d.ts

@@ -31,9 +31,22 @@ export interface GlobalRule {
     overrideKey: string | null;
     position: Position | null;
 }
+export interface Compose {
+    names: string[];
+    from: {
+        type: 'local';
+    } | {
+        type: 'global';
+    } | {
+        type: 'file';
+        path: string;
+    };
+    position: Position | null;
+}
 export interface ParsedBlock {
     atoms: Atom[];
     globals: GlobalRule[];
+    composes: Compose[];
 }
 export declare class PreStyleError extends Error {
     readonly position: Position | null;
@@ -41,12 +54,14 @@ export declare class PreStyleError extends Error {
 }
 export interface SassCompiler {
     compileString(source: string, options?: {
+        url?: URL;
         logger?: {
             warn?(message: string): void;
             debug?(message: string): void;
         };
     }): {
         css: string;
+        loadedUrls?: URL[];
     };
 }
 export interface ParseOptions {
@@ -55,8 +70,21 @@ export interface ParseOptions {
     sass: SassCompiler | null;
     warn: (message: string) => void;
 }
+export declare const key: (value: unknown) => string;
 export declare function parseBlock(code: string, lang: Lang, options: ParseOptions): ParsedBlock;
+export declare function parseRules(css: string, lightningcss: LightningOptions, position: ToPosition, collect: (rules: Rule[]) => void): void;
+export declare function dropOverridden(atoms: Atom[]): Atom[];
+export type ToPosition = (loc: {
+    line: number;
+    column: number;
+} | undefined) => Position | null;
 export declare const valueOf: (rule: Rule) => Record<string, any>;
+export declare function walk(rules: Rule[], atRules: AtRuleSegment[], variant: SelectorList | null, parsed: ParsedBlock, position: ToPosition): void;
+export declare function addDeclarations(block: {
+    declarations?: Declaration[];
+    importantDeclarations?: Declaration[];
+} | undefined, atRules: AtRuleSegment[], selectors: SelectorList, atoms: Atom[], composes: Compose[] | null, position: Position | null): void;
+export declare function addGlobal(rule: Rule, atRules: AtRuleSegment[], globals: GlobalRule[], position: ToPosition): void;
 export declare function propertyOf(declaration: Declaration): {
     property: string;
     shorthand: boolean;

package/dist/compiler/block.js

@@ -14,7 +14,7 @@ export class PreStyleError extends Error {
 }
 // JSON keys used to deduplicate. Locations are left out, so identical rules
 // from different places share a key.
-const key = (value) => JSON.stringify(value, (k, v) => (k === 'loc' ? undefined : v));
+export const key = (value) => JSON.stringify(value, (k, v) => (k === 'loc' ? undefined : v));
 const HOIST_ORDER = { charset: 0, layer: 1, import: 2, namespace: 3 };
 const hoistOrder = (rule) => HOIST_ORDER[/^@([\w-]+)/.exec(rule)[1].toLowerCase()] ?? Infinity;
 // Joins rules onto one line.
@@ -78,38 +78,46 @@ export function parseBlock(code, lang, options) {
             });
         }
     }
-    const parsed = { atoms: [], globals: [] };
+    const parsed = { atoms: [], globals: [], composes: [] };
     // Sass output positions don't match the block, so scss atoms have none.
     const position = (loc) => lang === 'css' && loc ? toBlock(loc.line, loc.column) : null;
-    // Collected on exit, after the user's visitor has changed the rules.
-    const collect = {
+    parseRules(css, options.lightningcss, position, (rules) => walk(rules, [], null, parsed, position));
+    return {
+        atoms: dropOverridden(parsed.atoms),
+        globals: parsed.globals,
+        composes: parsed.composes,
+    };
+}
+// Parses CSS with Lightning CSS, and passes its rules to `collect` once the
+// user's visitor has changed them. `position` converts error locations.
+export function parseRules(css, lightningcss, position, collect) {
+    const exit = {
         StyleSheetExit(sheet) {
-            walk(sheet.rules, [], null, parsed, position);
+            collect(sheet.rules);
         },
     };
-    const { visitor, ...rest } = options.lightningcss;
+    const { visitor, ...rest } = lightningcss;
     try {
         transform({
             ...rest,
             filename: 'block.css',
             code: Buffer.from(css),
-            visitor: visitor ? composeVisitors([visitor, collect]) : collect,
+            visitor: visitor ? composeVisitors([visitor, exit]) : exit,
         });
     }
     catch (error) {
+        if (error instanceof PreStyleError)
+            throw error;
         const loc = error.loc;
         // Lightning CSS reports error lines from 1.
-        throw new PreStyleError(`Invalid CSS: ${error.message}`, lang === 'css' && loc ? toBlock(loc.line - 1, loc.column) : null, {
-            cause: error,
-        });
+        throw new PreStyleError(`Invalid CSS: ${error.message}`, loc ? position({ line: loc.line - 1, column: loc.column }) : null, { cause: error });
     }
-    return { atoms: dropOverridden(parsed.atoms), globals: parsed.globals };
 }
 // Within a block, a later declaration overrides an earlier one that sets the
 // same property under the same at-rules and selector variant, as in CSS.
 // `!important` declarations are collected after normal ones in each rule,
 // so they win. Identical atoms are kept once.
-function dropOverridden(atoms) {
+export function dropOverridden(atoms) {
     const seen = new Set();
     const kept = [];
     for (let i = atoms.length - 1; i >= 0; i--) {
@@ -129,14 +137,15 @@ function dropOverridden(atoms) {
 export const valueOf = (rule) => 'value' in rule && rule.value !== null ? rule.value : {};
 const ruleLoc = (rule) => valueOf(rule).loc;
 // Walks the rules. `variant` is the element's selector variant when inside a
-// rule that targets the element, and null outside one.
-function walk(rules, atRules, variant, parsed, position) {
+// rule that targets the element, and null outside one. Without the
+// placeholder, every rule is global.
+export function walk(rules, atRules, variant, parsed, position) {
     for (const rule of rules) {
         if (rule.type === 'style') {
             const { selectors, declarations, rules: children = [], loc } = rule.value;
             if (variant !== null) {
                 const composed = compose(variant, selectors);
-                addDeclarations(declarations, atRules, composed, parsed, position(loc));
+                addDeclarations(declarations, atRules, composed, parsed.atoms, null, position(loc));
                 walk(children, atRules, composed, parsed, position);
                 continue;
             }
@@ -151,15 +160,17 @@ function walk(rules, atRules, variant, parsed, position) {
                     other.push(selector);
             }
             if (other.length > 0)
-                addGlobal({ ...rule, value: { ...rule.value, selectors: other } }, atRules, parsed, position);
+                addGlobal({ ...rule, value: { ...rule.value, selectors: other } }, atRules, parsed.globals, position);
             if (element.length > 0) {
-                addDeclarations(declarations, atRules, element, parsed, position(loc));
+                // `composes` only works directly in the block, outside at-rules.
+                const composes = atRules.length === 0 && isElement(element) ? parsed.composes : null;
+                addDeclarations(declarations, atRules, element, parsed.atoms, composes, position(loc));
                 walk(children, atRules, element, parsed, position);
             }
             continue;
         }
         if (rule.type === 'nested-declarations' && variant !== null) {
-            addDeclarations(rule.value.declarations, atRules, variant, parsed, position(rule.value.loc));
+            addDeclarations(rule.value.declarations, atRules, variant, parsed.atoms, null, position(rule.value.loc));
             continue;
         }
         if (atRuleInfo(rule.type).atomic) {
@@ -171,20 +182,40 @@ function walk(rules, atRules, variant, parsed, position) {
             walk(children, [...atRules, segment], variant, parsed, position);
             continue;
         }
-        addGlobal(rule, atRules, parsed, position);
+        addGlobal(rule, atRules, parsed.globals, position);
     }
 }
-function addDeclarations(block, atRules, selectors, parsed, position) {
+const COMPOSES_PLACEMENT = "`composes` must come before the rule's other declarations, and can't be used inside nested selectors or at-rules.";
+const isComposes = (declaration) => declaration.property === 'unparsed' && declaration.value.propertyId.property === 'composes';
+// Adds a rule's declarations as atoms. `composes` declarations are added to
+// `composes` when it's given, and are an error where it isn't (inside
+// nested selectors and at-rules).
+export function addDeclarations(block, atRules, selectors, atoms, composes, position) {
     let variant = null;
     if (!isElement(selectors)) {
         const repaired = repair(selectors);
         variant = { key: key(repaired), selectors: repaired };
     }
+    if (block?.importantDeclarations?.some(isComposes))
+        throw new PreStyleError("`composes` can't be `!important`.", position);
+    let normal = block?.declarations ?? [];
+    // As in CSS Modules, `composes` comes before the rule's other declarations.
+    const leading = normal.findIndex((d) => !isComposes(d));
+    const own = leading === -1 ? normal.length : leading;
+    if (normal.slice(own).some(isComposes))
+        throw new PreStyleError(COMPOSES_PLACEMENT, position);
+    if (own > 0) {
+        if (composes === null)
+            throw new PreStyleError(COMPOSES_PLACEMENT, position);
+        for (const d of normal.slice(0, own))
+            composes.push(parseComposes(d, position));
+        normal = normal.slice(own);
+    }
     const add = (declarations = [], important) => {
         for (const declaration of declarations) {
             for (const value of expand(declaration)) {
                 const { property, shorthand } = propertyOf(value);
-                parsed.atoms.push({
+                atoms.push({
                     atRules,
                     variant,
                     declaration: { key: key(value) + (important ? '!' : ''), value, important },
@@ -195,11 +226,38 @@ function addDeclarations(block, atRules, selectors, parsed, position) {
             }
         }
     };
-    add(block?.declarations, false);
+    add(normal, false);
     add(block?.importantDeclarations, true);
 }
+const ident = (t) => t?.type === 'token' && t.value.type === 'ident' ? t.value.value : null;
+// Reads `composes: a b`, `composes: a from './file.css'`, or
+// `composes: a from global`.
+function parseComposes(declaration, position) {
+    const tokens = declaration.value.value.filter((t) => !(t.type === 'token' && t.value.type === 'white-space'));
+    const invalid = () => new PreStyleError('Invalid `composes`. Use `composes: a b;`, `composes: a from "./file.css";`, or `composes: a from global;`.', position);
+    const names = [];
+    let i = 0;
+    for (; i < tokens.length; i++) {
+        const name = ident(tokens[i]);
+        if (name === null || name === 'from')
+            break;
+        names.push(name);
+    }
+    if (names.length === 0)
+        throw invalid();
+    if (i === tokens.length)
+        return { names, from: { type: 'local' }, position };
+    if (ident(tokens[i]) !== 'from' || tokens.length !== i + 2)
+        throw invalid();
+    const source = tokens[i + 1];
+    if (ident(source) === 'global')
+        return { names, from: { type: 'global' }, position };
+    if (source.type === 'token' && source.value.type === 'string')
+        return { names, from: { type: 'file', path: source.value.value }, position };
+    throw invalid();
+}
 // Global rules inside at-rules keep their at-rules around them.
-function addGlobal(rule, atRules, parsed, position) {
+export function addGlobal(rule, atRules, globals, position) {
     let wrapped = rule;
     for (const segment of atRules.toReversed()) {
         wrapped = {
@@ -209,7 +267,7 @@ function addGlobal(rule, atRules, parsed, position) {
     }
     const info = atRules.length === 0 ? atRuleInfo(rule.type) : atRuleInfo('');
     wrapped = repair(wrapped);
-    parsed.globals.push({
+    globals.push({
         key: key(wrapped),
         rule: wrapped,
         hoist: info.hoist,

package/dist/compiler/compiler.d.ts

@@ -25,14 +25,27 @@ export interface Block {
     line?: number;
     column?: number;
 }
+export interface Stylesheet {
+    code: string;
+    lang: Lang;
+    file: string;
+}
+export interface CompiledStylesheet {
+    exports: [name: string, classString: string][];
+    dependencies: string[];
+}
 export declare function createCompiler(options?: CompilerOptions): Promise<Compiler>;
 export declare class Compiler {
     #private;
     constructor(options: CompilerOptions, sass: SassCompiler | null);
     get revision(): number;
     scan(block: Block): void;
+    scanStylesheet(sheet: Stylesheet): void;
     assignNames(): void;
     classString(block: Block): string;
+    dependencies(block: Block): string[];
+    classNames(sheet: Stylesheet): string[];
+    stylesheet(sheet: Stylesheet): CompiledStylesheet;
     css(): Printed;
     cnTable(): CnTable;
 }