@pre.style/core 3.1.0-alpha.1 → 3.1.0-alpha.2

package/README.md

@@ -1,6 +1,6 @@
 # pre.style
 
-[![npm version](https://badge.fury.io/js/pre.style.svg)](https://www.npmjs.com/package/@pre.style/core)
+[![npm version](https://img.shields.io/npm/v/@pre.style/core/next)](https://www.npmjs.com/package/@pre.style/core)
 
 Zero-runtime CSS-in-JS. Write plain CSS or SCSS next to your markup, and pre.style compiles it at build time into atomic CSS classes: one small class per declaration, shared across your whole project.
 
@@ -252,7 +252,7 @@ const className = cn(button, isDanger && danger);
 
 Two classes conflict when they set the same property under the same at-rules and selector. A later shorthand also removes earlier longhands it covers.
 
-When every argument is a block or a string literal, the plugin resolves the call during the build, so it costs nothing at runtime. Other calls use a small lookup table the plugin generates for your project.
+When every argument is a block or a string literal, the plugin resolves the call during the build, so it costs nothing at runtime. Arguments can also name a top-level `const` holding one of these, or holding another call that's resolved this way (`const base = css`…`;` then `cn(base, …)`). Other calls use a small lookup table the plugin generates for your project.
 
 > **Note:** `cn` removes `!important` declarations too. A later class that sets the same property wins, even when the earlier one is `!important`.
 
@@ -608,7 +608,7 @@ preStyle({
 | Option          | Default                          | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
 | --------------- | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `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`     | `true` in dev, `false` in builds | 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`, unless you set it). 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.                                                                                                        |
+| `sourceMap`     | `true` in dev, `false` in builds | Generate a source map for the CSS, mapping each class to the first block it appears in (a source map can only point to one place; the [DevTools extension](#tracing-classes-with-the-devtools-extension) lists them all). In dev, it's shown in the browser (the plugin turns on Vite's `css.devSourcemap`, unless you set it). 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.                                                                                                        |
 | `layer`         | `false`                          | Wrap the CSS in a [cascade layer](https://developer.mozilla.org/docs/Web/CSS/@layer): `false` for none, `""` for an unnamed layer, or the layer's name, such as `"pre.style"` or `"vendor.pre-style"`. `@import` and `@namespace` rules stay before the layer, since they can't be inside one. `@layer` rules from blocks become layers nested in it. Browsers without cascade layers (Chrome before 99, Safari before 15.4, Firefox before 97) ignore everything inside it. |
 | `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`.                                                                                                                                                                                                                                                                                                                                                                                                            |
@@ -619,6 +619,14 @@ 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`.
 
+### Tracing classes with the DevTools extension
+
+Classes are shared, so one class can come from many blocks, and a source map can only point to one of them. The [pre.style DevTools extension](packages/devtools) adds a **pre.style** tab to the Elements panel in Chrome and Firefox. For the selected element, it lists each pre.style rule like the Styles pane does, with a link to every block that uses it.
+
+It works with the Vite dev server while `sourceMap` is on, which is the default in dev. Setting `sourceMap: false` turns it off. It only runs on `localhost`, `*.localhost`, loopback addresses, and hostnames you add in its settings, and sends other sites no requests.
+
+Its links open your editor through Vite, which guesses which one you use. When the dev server runs in VS Code's terminal, the plugin sets the `LAUNCH_EDITOR` environment variable to `code` if it isn't set, which also applies to Vite's error overlay. To choose an editor yourself, set `LAUNCH_EDITOR`.
+
 ### Quirks mode
 
 > [!WARNING]
@@ -668,6 +676,7 @@ The build fails, with the file, line, and column, when:
 | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `@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.                                                                                                                                                                             |
+| [pre.style DevTools](packages/devtools) | A side pane for the Elements panel in Chrome and Firefox that lists every block using each class. Not published to the extension stores yet. |
 
 ## Development
 

package/dist/compiler/compiler.d.ts

@@ -37,6 +37,23 @@ export interface CompiledStylesheet {
     exports: [name: string, classString: string][];
     dependencies: string[];
 }
+export interface Source {
+    file: string;
+    line: number;
+    column: number;
+}
+export interface ClassUsage {
+    className: string;
+    selector: string;
+    atRules: string[];
+    declaration: string;
+    property: string;
+    covers: string[];
+    important: boolean;
+    specificity: [ids: number, classes: number, types: number];
+    order: number;
+    sources: Source[];
+}
 export declare function createCompiler(options?: CompilerOptions): Promise<Compiler>;
 export declare class Compiler {
     #private;
@@ -48,6 +65,8 @@ export declare class Compiler {
     classString(block: Block): string;
     dependencies(block: Block): string[];
     classNames(sheet: Stylesheet): string[];
+    usages(classNames: Iterable<string>): ClassUsage[];
+    forgetSources(file: string): void;
     stylesheet(sheet: Stylesheet): CompiledStylesheet;
     css(): Printed;
     cnTable(): CnTable;

package/dist/compiler/compiler.js

@@ -4,9 +4,10 @@ import { transform } from 'lightningcss';
 import SweatMap from 'sweatmap';
 import { dropOverridden, parseBlock, PreStyleError, valueOf } from './block.js';
 import { print } from './print.js';
-import { lvhfaRank, withClass } from './selectors.js';
+import { lvhfaRank, specificity, withClass } from './selectors.js';
 import { KEYFRAMES_PREFIX } from './keyframes.js';
 import { MARKER_PREFIX, markerKey, parseStylesheet } from './stylesheet.js';
+import { SHORTHANDS } from '../shorthands.js';
 const RANGES = {
     Digits: { start: '0030', end: '0039' },
     Uppercase: { start: '0041', end: '005A' },
@@ -155,6 +156,34 @@ export class Compiler {
             throw error instanceof PreStyleError ? locate(error, fileBlock(sheet.file)) : error;
         }
     }
+    // Where each of the given classes is used, in output order. Classes that
+    // aren't in the output are left out. Sources are only kept with `sourceMap`
+    // on, and only list what has been compiled so far.
+    usages(classNames) {
+        const wanted = new Set(classNames);
+        const usages = [];
+        let order = 0;
+        const walk = (group) => {
+            for (const record of sortAtoms(group.atoms)) {
+                order++;
+                if (record.className !== null && wanted.has(record.className))
+                    usages.push(this.#usage(record, order));
+            }
+            for (const child of sortGroups([...group.children.values()]))
+                walk(child);
+        };
+        walk(this.#atomGroups());
+        return usages;
+    }
+    // Drops the places a file uses atoms, because it changed. They're added back
+    // as its blocks are compiled again. The atoms stay, like the rest of dev's
+    // output, which only grows.
+    forgetSources(file) {
+        for (const record of this.#atoms.values())
+            for (const [key, source] of record.sources)
+                if (source.file === file)
+                    record.sources.delete(key);
+    }
     // Each class of a stylesheet file, with its class string.
     stylesheet(sheet) {
         const parsed = this.#parseSheet(sheet);
@@ -391,14 +420,21 @@ export class Compiler {
     #register(block, parsed) {
         for (const atom of parsed.atoms) {
             const key = atomKey(atom);
-            if (!this.#atoms.has(key)) {
-                this.#atoms.set(key, {
+            const source = sourceOf(block, atom.position);
+            let record = this.#atoms.get(key);
+            if (record === undefined) {
+                record = {
                     atom,
                     className: null,
                     order: this.#order++,
-                    source: sourceOf(block, atom.position),
-                });
+                    source,
+                    sources: new Map(),
+                    printed: null,
+                };
+                this.#atoms.set(key, record);
             }
+            if (source !== null && this.#options.sourceMap)
+                record.sources.set(`${source.file}:${source.line}:${source.column}`, source);
         }
         for (const global of parsed.globals) {
             if (this.#globals.has(global.key))
@@ -420,8 +456,8 @@ export class Compiler {
     #nameOf(record) {
         return (record.className ??= this.#names.atoms.set(atomKey(record.atom)));
     }
-    #atomRules(loc) {
-        // Group atoms by their at-rules, nesting groups the same way.
+    // Atoms grouped by their at-rules, nesting groups the same way.
+    #atomGroups() {
         const root = { segment: null, order: 0, atoms: [], children: new Map() };
         for (const record of this.#atoms.values()) {
             let group = root;
@@ -435,25 +471,35 @@ export class Compiler {
             }
             group.atoms.push(record);
         }
+        return root;
+    }
+    #atomSelectors(record) {
+        const { atom } = record;
+        const className = this.#nameOf(record);
+        const selectors = atom.variant
+            ? withClass(atom.variant.selectors, className)
+            : [[{ type: 'class', name: className }]];
+        return atom.variant?.key.includes(MARKER_KEY) ? this.#named(selectors) : selectors;
+    }
+    #atomRule(record, loc) {
+        const { atom } = record;
+        const value = atom.declaration.key.includes(KEYFRAMES_KEY)
+            ? this.#named(atom.declaration.value)
+            : atom.declaration.value;
+        const declarations = atom.declaration.important
+            ? { importantDeclarations: [value] }
+            : { declarations: [value] };
+        return {
+            type: 'style',
+            value: { selectors: this.#atomSelectors(record), declarations, rules: [], loc },
+        };
+    }
+    #atomRules(loc) {
         const emit = (group) => {
             const rules = sortAtoms(group.atoms).map((record) => {
-                const { atom, source } = record;
-                const className = this.#nameOf(record);
-                let selectors = atom.variant
-                    ? withClass(atom.variant.selectors, className)
-                    : [[{ type: 'class', name: className }]];
-                if (atom.variant?.key.includes(MARKER_KEY))
-                    selectors = this.#named(selectors);
-                const value = atom.declaration.key.includes(KEYFRAMES_KEY)
-                    ? this.#named(atom.declaration.value)
-                    : atom.declaration.value;
-                const declarations = atom.declaration.important
-                    ? { importantDeclarations: [value] }
-                    : { declarations: [value] };
-                return {
-                    type: 'style',
-                    value: { selectors, declarations, rules: [], loc: loc(source) },
-                };
+                // The first place it's still used, since `forgetSources` drops places.
+                const [source = record.source] = record.sources.values();
+                return this.#atomRule(record, loc(source));
             });
             for (const child of sortGroups([...group.children.values()])) {
                 rules.push({
@@ -463,7 +509,36 @@ export class Compiler {
             }
             return rules;
         };
-        return emit(root);
+        return emit(this.#atomGroups());
+    }
+    #usage(record, order) {
+        const { atom } = record;
+        const loc = { source_index: 0, line: 0, column: 1 };
+        const rule = this.#atomRule(record, loc);
+        // Printed for reading, so without the user's `minify` and `targets`.
+        const { drafts, nonStandard, errorRecovery } = this.#parseOptions.lightningcss;
+        const text = (rules) => print([rules], [], { drafts, nonStandard, errorRecovery }, false).code;
+        const code = (record.printed ??= text(rule));
+        const open = code.indexOf(' {\n');
+        return {
+            className: record.className,
+            selector: code.slice(0, open).replaceAll('\n', ' '),
+            atRules: atom.atRules.map((segment) => {
+                const wrapped = { ...valueOf(segment.rule), rules: [rule] };
+                const printed = text({ type: segment.rule.type, value: wrapped });
+                return printed.slice(0, printed.indexOf(' {\n'));
+            }),
+            declaration: code
+                .slice(open + 3, code.lastIndexOf('\n}'))
+                .trim()
+                .replace(/;$/, ''),
+            property: atom.property,
+            covers: Object.hasOwn(SHORTHANDS, atom.property) ? SHORTHANDS[atom.property] : [],
+            important: atom.declaration.important,
+            specificity: specificity(this.#atomSelectors(record)),
+            order,
+            sources: [...record.sources.values()],
+        };
     }
 }
 // Markers and localized keyframes names as they appear in JSON keys, which

package/dist/compiler/index.d.ts

@@ -1,5 +1,5 @@
 export { Compiler, createCompiler } from './compiler.ts';
-export type { Block, CompiledStylesheet, CompilerOptions, Library, PrependFiles, Stylesheet, } from './compiler.ts';
+export type { Block, ClassUsage, CompiledStylesheet, CompilerOptions, Library, PrependFiles, Source, Stylesheet, } from './compiler.ts';
 export { PreStyleError } from './block.ts';
 export type { Lang, LightningOptions, Position } from './block.ts';
 export type { Printed } from './print.ts';

package/dist/compiler/selectors.d.ts

@@ -6,3 +6,6 @@ export declare function compose(parent: SelectorList, child: SelectorList): Sele
 export declare function withClass(selectors: SelectorList, className: string): SelectorList;
 export declare function lvhfaRank(selectors: SelectorList): number;
 export declare function repair<T>(selectors: T): T;
+type Specificity = [ids: number, classes: number, types: number];
+export declare function specificity(selectors: SelectorList): Specificity;
+export {};

package/dist/compiler/selectors.js

@@ -128,3 +128,41 @@ export function repair(selectors) {
     };
     return fix(selectors);
 }
+// A selector list's specificity: its most specific selector's.
+export function specificity(selectors) {
+    let best = [0, 0, 0];
+    for (const selector of selectors) {
+        const current = ofSelector(selector);
+        const difference = current[0] - best[0] || current[1] - best[1] || current[2] - best[2];
+        if (difference > 0)
+            best = current;
+    }
+    return best;
+}
+function ofSelector(selector) {
+    const total = [0, 0, 0];
+    const add = (other) => {
+        total[0] += other[0];
+        total[1] += other[1];
+        total[2] += other[2];
+    };
+    for (const component of selector) {
+        if (component.type === 'id')
+            total[0]++;
+        else if (component.type === 'class' || component.type === 'attribute')
+            total[1]++;
+        else if (component.type === 'type' || component.type === 'pseudo-element')
+            total[2]++;
+        else if (component.type === 'pseudo-class' && component.kind !== 'where') {
+            // `:is()`, `:not()`, and `:has()` count as their most specific argument.
+            if (component.selectors)
+                add(specificity(component.selectors));
+            else {
+                total[1]++;
+                if (component.of)
+                    add(specificity(component.of));
+            }
+        }
+    }
+    return total;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pre.style/core",
-  "version": "3.1.0-alpha.1",
+  "version": "3.1.0-alpha.2",
   "description": "Zero-runtime CSS-in-JS that compiles css and scss blocks into atomic CSS classes.",
   "keywords": [
     "atomic-css",