@pre.style/core 3.1.0-alpha.4 → 3.1.0-alpha.5

package/README.md

@@ -922,13 +922,40 @@ Expanding means some shorthands produce many classes. For example, `font` also r
 
 ### Order
 
-Within one block, a later declaration overrides an earlier one, as in plain CSS. Across blocks, the CSS file is ordered so the usual rules hold:
+Within one block, a later declaration overrides an earlier one, as in plain CSS (see [Fallbacks](#fallbacks) for the same property twice in a row). Across blocks, the CSS file is ordered so the usual rules hold:
 
 1. Hoisted at-rules (`@layer` statements, `@import`, `@namespace`), then other copied at-rules. With the `layer` option, everything but `@import` and `@namespace` is inside the layer.
 2. Classes on the element.
 3. Selector variants, with pseudo-classes in LVHFA order (`:link`, `:visited`, `:hover`, `:focus`, `:active`).
 4. At-rule groups. `@media` queries with only a `min-width` come last, smallest first (mobile-first).
 
+### Fallbacks
+
+Declaring the same property more than once in a rule keeps the earlier values as fallbacks, for browsers that can't parse the later ones. They stay together in one class:
+
+```ts
+css`
+  height: 100%;
+  height: 100svh;
+`;
+```
+
+```css
+.A {
+  height: 100%;
+  height: 100svh;
+}
+```
+
+Lightning CSS drops the fallbacks your [`targets`](#configuration) don't need, so set `targets` to keep them. Without `targets`, it assumes current browsers and writes only `height: 100svh` (which then shares a class with any other `height: 100svh`). Values it can't parse, such as `calc-size()`, always keep their fallbacks.
+
+A few things aren't fallbacks:
+
+- **A declaration in another rule**, such as `height: 100%; & { height: 100svh; }`, overrides the earlier one, since separate rules become separate classes.
+- **A value with `var()`, `env()`, or `${…}`** replaces the declarations before it. Browsers only check these values when they're used, so they never fall back: an invalid value, or a `${…}` that is `null`, makes the property `unset`. To fall back from `${…}`, use a default (`height: var(${h}, 100%)`). A `${…}` followed by a static value is a real fallback (`height: ${h}; height: 100svh`).
+- **Custom properties**, which accept any value.
+- **Shorthands** are expanded into longhands, so `background: red; background: linear-gradient(…)` loses the `red`: the gradient's `background-color` (transparent) is a valid value in every browser.
+
 ## Compared to utility-first frameworks
 
 Utility-first frameworks such as [Tailwind CSS](https://tailwindcss.com/) also produce atomic CSS, so the same styles cost about the same in either. The differences are elsewhere:
@@ -1006,6 +1033,7 @@ preStyle({
 | --------------- | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `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 (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.                                                                                                        |
+| `sourceAttributes` | `true` in dev, except in test runs | In dev, mark each `className`/`class` attribute in JSX and Astro components with where it's written (as `data-pre-style-at` on elements and `data-pre-style-from` on components), so the [DevTools extension](#tracing-classes-with-the-devtools-extension) can link an element to the line that set its classes. Needs `sourceMap`. Off by default in Vite's `test` mode (as in Vitest), so rendered markup and snapshots don't change; set it to `true` to have them there too. Builds never have the attributes. |
 | `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`.                                                                                                                                                                                                                                                                                                                                                                                                            |
@@ -1020,7 +1048,15 @@ Before 3.1, `include`, `exclude`, `prependFiles`, `libraries`, and `quirksMode`
 
 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.
+It works with the Vite dev server while `sourceMap` is on, which is the default in dev. Setting `sourceMap: false` turns it off.
+
+It also links to where the element got its classes: the `className` or `class` attribute on the element, and the one on the component it was passed to, when the component passes its props on. For this, the plugin adds `data-pre-style-at` and `data-pre-style-from` attributes to your JSX and Astro components in dev (not in builds or test runs), which you'll see in the Elements panel. If you'd rather not see them, turn them off with the `sourceAttributes` option.
+
+```ts
+preStyle({ sourceAttributes: false });
+```
+
+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`.
 

package/dist/compiler/block.d.ts

@@ -16,15 +16,17 @@ export interface Atom {
         key: string;
         selectors: SelectorList;
     } | null;
-    declaration: {
-        key: string;
-        value: Declaration;
-        important: boolean;
-    };
+    declaration: AtomDeclaration;
     property: string;
     shorthand: boolean;
     position: Position | null;
 }
+export interface AtomDeclaration {
+    key: string;
+    values: Declaration[];
+    important: boolean;
+}
+export declare const atomDeclaration: (values: Declaration[], important: boolean) => AtomDeclaration;
 export interface GlobalRule {
     key: string;
     rule: Rule;
@@ -77,6 +79,7 @@ export interface ParseOptions {
 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 pruneFallbacks(atoms: Atom[], lightningcss: LightningOptions): Atom[];
 export declare function dropOverridden(atoms: Atom[]): Atom[];
 export type ToPosition = (loc: {
     line: number;

package/dist/compiler/block.js

@@ -5,9 +5,16 @@ import { localizeCustomProperties } from './custom-properties.js';
 import { SLOT_PREFIX } from './interpolate.js';
 import { localizeKeyframes } from './keyframes.js';
 import { compose, fromPlaceholder, isElement, PLACEHOLDER, repair } from './selectors.js';
+import { print } from './print.js';
 import { splitBlock } from './split.js';
 import { extractVariables } from './variables.js';
 import { SHORTHANDS } from '../shorthands.js';
+// An atom's declaration. A single declaration's key is its own key.
+export const atomDeclaration = (values, important) => ({
+    key: key(values.length === 1 ? values[0] : values) + (important ? '!' : ''),
+    values,
+    important,
+});
 export class PreStyleError extends Error {
     position;
     constructor(message, position, options) {
@@ -86,7 +93,7 @@ export function parseBlock(code, lang, options) {
     // 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;
     parseRules(css, options.lightningcss, position, (rules) => walk(rules, [], null, parsed, position));
-    let atoms = dropOverridden(parsed.atoms);
+    let atoms = dropOverridden(pruneFallbacks(parsed.atoms, options.lightningcss));
     let { globals } = parsed;
     if (options.customPropertyLocalization) {
         const local = localizeCustomProperties(atoms, globals, `block\n${code}`, lang, options);
@@ -127,6 +134,60 @@ export function parseRules(css, lightningcss, position, collect) {
         throw new PreStyleError(`Invalid CSS: ${error.message}`, loc ? position({ line: loc.line - 1, column: loc.column }) : null, { cause: error });
     }
 }
+// Drops the fallbacks in each stack that Lightning CSS wouldn't print for the
+// user's targets, so a stack that collapses to one declaration shares its
+// class. Values Lightning CSS can't parse (such as `calc-size()`) are kept.
+// Printing and parsing back changes some values' trees, so the round trip
+// only decides which of the original declarations are kept.
+export function pruneFallbacks(atoms, lightningcss) {
+    if (atoms.every((atom) => atom.declaration.values.length === 1))
+        return atoms;
+    const { visitor: _visitor, minify: _minify, ...options } = lightningcss;
+    // The stack as Lightning CSS prints it, parsed back, as keys. Declarations
+    // it adds for other properties (vendor prefixes) are left out.
+    const printed = (stack, important, property) => {
+        const block = important ? { importantDeclarations: stack } : { declarations: stack };
+        const rule = {
+            type: 'style',
+            value: {
+                selectors: [[{ type: 'class', name: 'x' }]],
+                declarations: block,
+                rules: [],
+                loc: { source_index: 0, line: 0, column: 1 },
+            },
+        };
+        let values = [];
+        parseRules(print([rule], [], options, false).code, options, () => null, (rules) => {
+            const parsed = valueOf(rules[0]).declarations ?? {};
+            values = (important ? parsed.importantDeclarations : parsed.declarations) ?? [];
+        });
+        return values.filter((value) => propertyOf(value).property === property).map(key);
+    };
+    return atoms.map((atom) => {
+        const { values: stack, important } = atom.declaration;
+        if (stack.length === 1)
+            return atom;
+        let kept;
+        try {
+            const remaining = printed(stack, important, atom.property);
+            if (remaining.length === stack.length)
+                return atom;
+            kept = stack.filter((value) => {
+                const own = printed([value], important, atom.property).at(-1);
+                if (own !== remaining[0])
+                    return false;
+                remaining.shift();
+                return true;
+            });
+        }
+        catch {
+            return atom;
+        }
+        if (kept.length === 0)
+            return atom;
+        return { ...atom, declaration: atomDeclaration(kept, important) };
+    });
+}
 // 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,
@@ -225,24 +286,43 @@ export function addDeclarations(block, atRules, selectors, atoms, composes, posi
             composes.push(parseComposes(d, position));
         normal = normal.slice(own);
     }
+    // Declarations of the same property in this list are stacked, in order, as
+    // fallbacks, at the place of the last one. A declaration that always parses
+    // replaces the stack, since nothing before it can ever apply.
     const add = (declarations = [], important) => {
+        const stacks = new Map();
+        const list = [];
         for (const declaration of declarations) {
             for (const value of expand(declaration)) {
                 const { property, shorthand } = propertyOf(value);
-                atoms.push({
-                    atRules,
-                    variant,
-                    declaration: { key: key(value) + (important ? '!' : ''), value, important },
-                    property,
-                    shorthand,
-                    position,
-                });
+                const stack = stacks.get(property);
+                if (stack)
+                    list.splice(list.findIndex((item) => item.values === stack), 1);
+                const values = stack && !alwaysParses(value, property) ? [...stack, value] : [value];
+                stacks.set(property, values);
+                list.push({ property, shorthand, values });
             }
         }
+        for (const { property, shorthand, values } of list)
+            atoms.push({
+                atRules,
+                variant,
+                declaration: atomDeclaration(values, important),
+                property,
+                shorthand,
+                position,
+            });
     };
     add(normal, false);
     add(block?.importantDeclarations, true);
 }
+// Whether a browser always parses a declaration, so it can't fall back to an
+// earlier one: custom properties take any value, and `var()` and `env()`
+// (including `${…}`, which becomes a `var()`) are only checked once they're
+// substituted, when an invalid value makes the property `unset`.
+function alwaysParses(value, property) {
+    return property.startsWith('--') || /"type":"(?:var|env)"/.test(key(value));
+}
 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`.

package/dist/compiler/compiler.js

@@ -2,7 +2,7 @@ import { readFileSync } from 'node:fs';
 import { dirname, relative, resolve as resolvePath, sep } from 'node:path';
 import { transform } from 'lightningcss';
 import SweatMap from 'sweatmap';
-import { dropOverridden, parseBlock, PreStyleError, valueOf } from './block.js';
+import { atomDeclaration, dropOverridden, parseBlock, PreStyleError, valueOf } from './block.js';
 import { interpolate } from './interpolate.js';
 import { print } from './print.js';
 import { lvhfaRank, specificity, withClass } from './selectors.js';
@@ -544,12 +544,12 @@ export class Compiler {
     }
     #atomRule(record, loc) {
         const { atom } = record;
-        const value = hasGenerated(atom.declaration.key)
-            ? this.#named(atom.declaration.value)
-            : atom.declaration.value;
+        const values = hasGenerated(atom.declaration.key)
+            ? this.#named(atom.declaration.values)
+            : atom.declaration.values;
         const declarations = atom.declaration.important
-            ? { importantDeclarations: [value] }
-            : { declarations: [value] };
+            ? { importantDeclarations: values }
+            : { declarations: values };
         return {
             type: 'style',
             value: { selectors: this.#atomSelectors(record), declarations, rules: [], loc },
@@ -574,6 +574,20 @@ export class Compiler {
         };
         return emit(this.#atomGroups());
     }
+    // An atom's rule as text. Without the user's targets, Lightning CSS would
+    // drop a stack's fallbacks, so each declaration is printed on its own.
+    #printedStack(record, rule, text) {
+        const code = text(rule);
+        const { values, important } = record.atom.declaration;
+        if (values.length === 1)
+            return code;
+        const lines = values.map((value) => {
+            const atom = { ...record.atom, declaration: atomDeclaration([value], important) };
+            const own = text(this.#atomRule({ ...record, atom }, valueOf(rule).loc));
+            return own.slice(own.indexOf(' {\n') + 3, own.lastIndexOf('\n}'));
+        });
+        return `${code.slice(0, code.indexOf(' {\n'))} {\n${lines.join('\n')}\n}`;
+    }
     #usage(record, order) {
         const { atom } = record;
         const loc = { source_index: 0, line: 0, column: 1 };
@@ -581,7 +595,7 @@ export class Compiler {
         // 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 code = (record.printed ??= this.#printedStack(record, rule, text));
         const open = code.indexOf(' {\n');
         return {
             className: record.className,
@@ -595,7 +609,9 @@ export class Compiler {
             declaration: code
                 .slice(open + 3, code.lastIndexOf('\n}'))
                 .trim()
-                .replace(/;$/, ''),
+                .replace(/;$/, '')
+                // Fallbacks, on one line.
+                .replaceAll(/;\n\s*/g, '; '),
             property: this.#propertyName(atom.property),
             covers: Object.hasOwn(SHORTHANDS, atom.property) ? SHORTHANDS[atom.property] : [],
             important: atom.declaration.important,

package/dist/compiler/custom-properties.js

@@ -1,5 +1,5 @@
 import { createHash } from 'node:crypto';
-import { key, overrideKey, parseRules, valueOf, walk } from './block.js';
+import { atomDeclaration, key, overrideKey, parseRules, valueOf, walk } from './block.js';
 import { VARIABLE_PREFIX } from './variables.js';
 // With `customPropertyLocalization`, a custom property that a block or
 // stylesheet file declares gets a generated name, used only in that block or
@@ -103,7 +103,7 @@ export function localizeCustomProperties(atoms, globals, scope, lang, options) {
         local.set(name, VARIABLE_PREFIX + hash);
     };
     for (const atom of atoms)
-        eachDeclared(atom.declaration.value, declared);
+        eachDeclared(atom.declaration.values, declared);
     const own = (global) => !shared.keys.has(global.key);
     for (const global of globals)
         if (own(global))
@@ -125,23 +125,19 @@ export function localizeCustomProperties(atoms, globals, scope, lang, options) {
             };
         }),
         atoms: (list) => list.map((atom) => {
-            const value = rename(atom.declaration.value, local);
+            const values = rename(atom.declaration.values, local);
             const atRules = atom.atRules.map((segment) => {
                 const rule = rename(segment.rule, local);
                 return rule === segment.rule ? segment : { key: key(valueKey(rule)), rule };
             });
-            const unchanged = value === atom.declaration.value && atRules.every((s, i) => s === atom.atRules[i]);
+            const unchanged = values === atom.declaration.values && atRules.every((s, i) => s === atom.atRules[i]);
             if (unchanged)
                 return atom;
             return {
                 ...atom,
                 atRules,
                 property: local.get(atom.property) ?? atom.property,
-                declaration: {
-                    ...atom.declaration,
-                    key: key(value) + (atom.declaration.important ? '!' : ''),
-                    value,
-                },
+                declaration: atomDeclaration(values, atom.declaration.important),
             };
         }),
     };

package/dist/compiler/keyframes.js

@@ -1,5 +1,5 @@
 import { createHash } from 'node:crypto';
-import { key, overrideKey, valueOf } from './block.js';
+import { atomDeclaration, key, overrideKey, valueOf } from './block.js';
 // With `keyframeLocalization`, each `@keyframes` name is replaced with a
 // generated one, like styled-components' `keyframes`. In parsed rules, a
 // local name is an ident with this prefix and a hash of every definition of
@@ -55,17 +55,10 @@ export function localizeKeyframes(globals) {
         atoms: (atoms) => atoms.map((atom) => {
             if (!ANIMATION_PROPERTIES.has(atom.property.replace(/^-\w+-/, '')))
                 return atom;
-            const value = renameIdents(atom.declaration.value, local);
-            if (value === atom.declaration.value)
+            const values = renameIdents(atom.declaration.values, local);
+            if (values === atom.declaration.values)
                 return atom;
-            return {
-                ...atom,
-                declaration: {
-                    ...atom.declaration,
-                    key: key(value) + (atom.declaration.important ? '!' : ''),
-                    value,
-                },
-            };
+            return { ...atom, declaration: atomDeclaration(values, atom.declaration.important) };
         }),
     };
 }

package/dist/compiler/stylesheet.js

@@ -1,6 +1,6 @@
 import { pathToFileURL, fileURLToPath } from 'node:url';
 import { atRuleInfo } from './at-rules.js';
-import { addDeclarations, addGlobal, dropOverridden, key, parseRules, PreStyleError, valueOf, walk, } from './block.js';
+import { addDeclarations, addGlobal, dropOverridden, pruneFallbacks, key, parseRules, PreStyleError, valueOf, walk, } from './block.js';
 import { localizeCustomProperties } from './custom-properties.js';
 import { localizeKeyframes } from './keyframes.js';
 import { compose, isElement } from './selectors.js';
@@ -145,7 +145,7 @@ export function parseStylesheet(code, lang, file, id, options) {
         }
     }
     for (const target of classes.values())
-        target.atoms = dropOverridden(target.atoms);
+        target.atoms = dropOverridden(pruneFallbacks(target.atoms, options.lightningcss));
     // Custom properties are local to the whole file, like keyframes.
     if (options.customPropertyLocalization) {
         const all = [...classes.values()].flatMap((target) => target.atoms);

package/dist/compiler/variables.js

@@ -1,6 +1,6 @@
 import { createHash } from 'node:crypto';
 import { transform } from 'lightningcss';
-import { key, overrideKey, PreStyleError, valueOf } from './block.js';
+import { atomDeclaration, key, overrideKey, PreStyleError, valueOf } from './block.js';
 import { atRuleInfo } from './at-rules.js';
 import { SLOT_PREFIX } from './interpolate.js';
 import { print } from './print.js';
@@ -43,7 +43,9 @@ const IGNORED = (token) => token.type === 'token' && token.value?.type === 'whit
 function directSlot(atom) {
     if (atom.atRules.length > 0 || atom.variant !== null || atom.declaration.important)
         return null;
-    const declaration = atom.declaration.value;
+    if (atom.declaration.values.length !== 1)
+        return null;
+    const declaration = atom.declaration.values[0];
     // Lightning CSS also uses `custom` for properties it doesn't parse, such as
     // `content` with a `var()`.
     if (declaration.property !== 'custom' || !atom.property.startsWith('--'))
@@ -251,22 +253,17 @@ export function extractVariables(atoms, globals) {
             }
             continue;
         }
-        const value = structuredClone(atom.declaration.value);
+        const values = structuredClone(atom.declaration.values);
         const selector = selectorOf(atom);
         let index = 0;
-        eachSlot(value, (node) => {
+        // Counted across the whole stack, so `height: ${a}; height: ${b}` is two
+        // variables.
+        eachSlot(values, (node) => {
             const { slot, syntax } = parseSlot(node);
             const identity = atomIdentity(atom, index++);
             useVariable(node, identity, slot, syntax, variables, added, atom.position, selector);
         });
-        keptAtoms.push({
-            ...atom,
-            declaration: {
-                ...atom.declaration,
-                key: key(value) + (atom.declaration.important ? '!' : ''),
-                value,
-            },
-        });
+        keptAtoms.push({ ...atom, declaration: atomDeclaration(values, atom.declaration.important) });
     }
     return { atoms: keptAtoms, globals: [...kept, ...added.values()], variables };
 }

package/package.json

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