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

package/README.md

@@ -1,11 +1,11 @@
 # pre.style
 
-[![npm version](https://badge.fury.io/js/pre.style.svg)](https://www.npmjs.com/package/pre.style)
+[![npm version](https://badge.fury.io/js/pre.style.svg)](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.
 
 ```js
-import { css } from '@pre.style/core';
+import { css } from "@pre.style/core";
 
 const button = css`
   background-color: #0071ba;
@@ -25,14 +25,28 @@ const button = css`
 After the build, `button` is a plain string, `"B C E D A G F"`. The block is replaced, and these classes are added to a single CSS file:
 
 ```css
-.B{background-color:#0071ba}
-.C{color:#fff}
-.E{padding-block-start:.5em}
-.D{padding-block-end:.5em}
-.A:hover{background-color:#005a94}
+.B {
+  background-color: #0071ba;
+}
+.C {
+  color: #fff;
+}
+.E {
+  padding-block-start: 0.5em;
+}
+.D {
+  padding-block-end: 0.5em;
+}
+.A:hover {
+  background-color: #005a94;
+}
 @media (width>=768px) {
-  .G{padding-block-start:1em}
-  .F{padding-block-end:1em}
+  .G {
+    padding-block-start: 1em;
+  }
+  .F {
+    padding-block-end: 1em;
+  }
 }
 ```
 
@@ -59,8 +73,8 @@ npm install --save-dev sass
 Add the plugin to `vite.config.ts`:
 
 ```ts
-import { defineConfig } from 'vite';
-import preStyle from '@pre.style/vite';
+import { defineConfig } from "vite";
+import preStyle from "@pre.style/vite";
 
 export default defineConfig({
   plugins: [preStyle()],
@@ -70,7 +84,7 @@ export default defineConfig({
 Then import `css` (or `scss`) from `@pre.style/core` and use the class strings:
 
 ```jsx
-import { css } from '@pre.style/core';
+import { css } from "@pre.style/core";
 
 export function Card({ children }) {
   return (
@@ -95,7 +109,7 @@ You can also write styles in `.css` and `.scss` files and import their classes,
 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:
 
 ```ts
-import 'virtual:pre.style.css';
+import "virtual:pre.style.css";
 ```
 
 Vite then bundles the CSS with your app's other CSS, and the framework links it when rendering on the server, both in builds and in dev. The plugin doesn't write `output.file` when the CSS is imported this way.
@@ -106,8 +120,8 @@ Add the plugin to Astro's Vite config, and import the CSS in your layout's front
 
 ```js
 // astro.config.mjs
-import { defineConfig } from 'astro/config';
-import preStyle from '@pre.style/vite';
+import { defineConfig } from "astro/config";
+import preStyle from "@pre.style/vite";
 
 export default defineConfig({
   vite: { plugins: [preStyle()] },
@@ -127,7 +141,7 @@ const title = css`
 <h1 class={title}>Hello</h1>
 ```
 
-Blocks work in frontmatter, in template expressions such as `` class={css`…`} ``, in `<script>` tags, and in the islands of any framework. Astro links the CSS on every page that uses the layout, prerendered or rendered on demand. Astro compiles components before the plugin sees them, but errors and source maps still point to the component.
+Blocks work in frontmatter, in template expressions such as ``class={css`…`}``, in `<script>` tags, and in the islands of any framework. Astro links the CSS on every page that uses the layout, prerendered or rendered on demand. Astro compiles components before the plugin sees them, but errors and source maps still point to the component.
 
 ## Writing blocks
 
@@ -138,7 +152,7 @@ A block styles one element. Each block is treated as its own small stylesheet, w
 `css` blocks are plain CSS. `scss` blocks are compiled with Sass first, so you can use variables, mixins, functions, and everything else Sass supports:
 
 ```js
-import { scss } from '@pre.style/core';
+import { scss } from "@pre.style/core";
 
 const title = scss`
   $size: 2rem;
@@ -161,7 +175,8 @@ css`
   &::before { content: '→'; }
   & > * + * { margin-top: 1rem; }
   .dark & { color: white; }
-  a { text-decoration: underline; } /* the same as `& a` */
+  a { text-decoration: underline; } /* the same as ` &
+  a` */
 `;
 ```
 
@@ -174,20 +189,32 @@ Other at-rules, such as `@keyframes`, `@font-face`, and `@property`, are copied
 ```js
 css`
   @keyframes fade-in {
-    from { opacity: 0; }
+    from {
+      opacity: 0;
+    }
   }
 
   animation: fade-in 200ms ease-out;
 `;
 ```
 
+#### Local keyframes
+
+By default, keyframes names are global, so two blocks that each define a different `@keyframes spin` collide, and the last one wins everywhere. Set `"keyframeLocalization": true` in your `package.json`'s `pre.style` field to give each `@keyframes` a generated name, as styled-components' `keyframes` helper does:
+
+- A block's or stylesheet file's `@keyframes` get a short generated name, and its `animation` and `animation-name` declarations use it. In a stylesheet file, every class in the file shares the file's keyframes, as in CSS Modules.
+- Keyframes with the same contents get the same name wherever they're defined, so they're written once.
+- Keyframes from [prepended files](#sharing-values-with-prepended-files) are localized too. Every block gets the same copy, so prepended files are the way to share keyframes between blocks.
+- Names a block or file doesn't define are left as they are, so `animation-name: spin` still refers to a global `@keyframes spin`, for example one in a CSS file that pre.style doesn't process. That also means a block can't use keyframes another block defines.
+- Names in custom properties (`--anim: spin`) aren't renamed, because pre.style can't tell they name keyframes.
+
 ### `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: button from "./button.css";
   composes: legacy-btn from global;
   color: white;
 `;
@@ -208,7 +235,7 @@ HTML can't import anything, so blocks in HTML files that Vite processes, such as
 Atomic classes all have the same specificity, so when two classes on one element set the same property, the order of the CSS file decides which wins, not the order in your `class` attribute. Use `cn` to combine class strings: when two classes conflict, it keeps the later one.
 
 ```js
-import { css, cn } from '@pre.style/core';
+import { css, cn } from "@pre.style/core";
 
 const button = css`
   background-color: #0071ba;
@@ -251,7 +278,10 @@ Styles can also live in `.css` and `.scss` files, imported with the `pre.style`
 ```
 
 ```jsx
-import { button, 'primary-button' as primaryButton } from './button.css' with { type: 'pre.style' };
+import {
+  button,
+  "primary-button" as primaryButton,
+} from "./button.css" with { type: "pre.style" };
 
 <button className={primaryButton}>Save</button>;
 ```
@@ -276,15 +306,27 @@ In `.scss` files, relative `@use`, `@forward`, and `@import` resolve from the fi
 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; }
+.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}
+.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"`.
@@ -297,10 +339,20 @@ Atomic classes are shared, so no single class in a class string identifies one e
 `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; }
+.base {
+  color: gray;
+  padding: 1rem;
+}
+.primary {
+  composes: base;
+  color: blue;
+}
+.wide {
+  composes: card from "./card.css";
+}
+.legacy {
+  composes: old-btn from global;
+}
 ```
 
 > [!IMPORTANT]
@@ -318,7 +370,9 @@ TypeScript 7.1 adds [content mappers](https://devblogs.microsoft.com/typescript/
 
 ```json
 {
-  "contentMappers": [{ "package": "@pre.style/core", "extensions": [".css", ".scss"] }]
+  "contentMappers": [
+    { "package": "@pre.style/core", "extensions": [".css", ".scss"] }
+  ]
 }
 ```
 
@@ -327,11 +381,11 @@ Content mappers run code from a package, so `tsc` needs the `--runExternalCode`
 Before TypeScript 7.1, add this declaration to your project instead (for example as `src/stylesheets.d.ts`):
 
 ```ts
-declare module '*.css' {
+declare module "*.css" {
   const classes: { readonly [name: string]: string };
   export = classes;
 }
-declare module '*.scss' {
+declare module "*.scss" {
   const classes: { readonly [name: string]: string };
   export = classes;
 }
@@ -340,7 +394,7 @@ declare module '*.scss' {
 TypeScript can't type named imports from it, so use a namespace import:
 
 ```ts
-import * as styles from './button.css' with { type: 'pre.style' };
+import * as styles from "./button.css" with { type: "pre.style" };
 
 styles.button;
 ```
@@ -411,11 +465,12 @@ 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. 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. |
+| Field                  | Default                      | Description                                                                                                                                                                                                                                       |
+| ---------------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `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.       |
+| `keyframeLocalization` | `false`                      | Give each `@keyframes` in the library's blocks and stylesheet files a generated name. See [Local keyframes](#local-keyframes). The library's setting applies to its blocks, whatever the app sets, since the library's styles are written for it. |
 
 `"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.
 
@@ -438,20 +493,33 @@ Production builds scan your files first, so names are stable between builds. In
 Shorthand properties are expanded into their longhands, so `cn` can resolve conflicts between them:
 
 ```js
-css`margin: auto;`;
+css`
+  margin: auto;
+`;
 ```
 
 ```css
-.D{margin-top:auto}
-.C{margin-right:auto}
-.A{margin-bottom:auto}
-.B{margin-left:auto}
+.D {
+  margin-top: auto;
+}
+.C {
+  margin-right: auto;
+}
+.A {
+  margin-bottom: auto;
+}
+.B {
+  margin-left: auto;
+}
 ```
 
 `border` (which sets 12 longhands), shorthands whose values aren't known until runtime (values with `var()`, `env()`, or `attr()`), and shorthands set to a CSS-wide keyword (`font: inherit`, `margin: initial`) are kept as one class. They're written before longhands, so a longhand still wins:
 
 ```js
-css`padding: var(--space); padding-top: 0;`;
+css`
+  padding: var(--space);
+  padding-top: 0;
+`;
 ```
 
 Expanding means some shorthands produce many classes. For example, `font` also resets the `font-variant-*` properties, among others, so it becomes about 20 classes. The CSS file barely grows, because the classes are shared across your project, but class strings get longer.
@@ -460,7 +528,7 @@ Expanding means some shorthands produce many classes. For example, `font` also r
 
 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:
 
-1. Hoisted at-rules (`@layer` statements, `@import`, `@namespace`), then other copied at-rules.
+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).
@@ -492,13 +560,14 @@ Options every tool that reads your styles has to agree on (the bundler plugin, a
 }
 ```
 
-| 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). |
+| 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).                                                                                                               |
+| `keyframeLocalization` | `false`                                           | Give each `@keyframes` in the app's blocks and stylesheet files a generated name, used only in the block or file that defines it. See [Local keyframes](#local-keyframes). Libraries use their own setting.                                                  |
 
 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:
 
@@ -509,7 +578,9 @@ The plugin warns about keys it doesn't know, and fails the build on values of th
       "fileMatch": ["package.json"],
       "schema": {
         "properties": {
-          "pre.style": { "$ref": "./node_modules/@pre.style/core/package.schema.json" }
+          "pre.style": {
+            "$ref": "./node_modules/@pre.style/core/package.schema.json"
+          }
         }
       }
     }
@@ -525,22 +596,24 @@ Options about how a build writes its output go to the plugin. All options are op
 preStyle({
   lightningcss: { minify: true, targets: { safari: 16 << 16 } },
   sourceMap: true,
-  quotes: 'single-quote',
+  layer: "pre.style",
+  quotes: "single-quote",
   output: {
-    file: 'css/pre.style.css',
-    banner: '/* Generated by pre.style */',
+    file: "css/pre.style.css",
+    banner: "/* Generated by pre.style */",
   },
 });
 ```
 
-| 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`    | `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. |
-| `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. |
-| `output.footer`|                                                   | Text added to the end of the CSS file. |
+| 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.                                                                                                        |
+| `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`.                                                                                                                                                                                                                                                                                                                                                                                                            |
+| `output.banner` |                                  | Text added to the start of the CSS file.                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `output.footer` |                                  | Text added to the end of the CSS file.                                                                                                                                                                                                                                                                                                                                                                                                                                       |
 
 The CSS isn't minified unless you set `lightningcss: { minify: true }`.
 
@@ -591,10 +664,10 @@ The build fails, with the file, line, and column, when:
 
 ## Packages
 
-| Package                 | Description                                            |
-| ----------------------- | ------------------------------------------------------ |
-| `@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.                                       |
+| Package           | Description                                                                                                                                                                                  |
+| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `@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
 

package/dist/compiler/block.d.ts

@@ -69,6 +69,7 @@ export interface ParseOptions {
     prepend: Record<Lang, string>;
     sass: SassCompiler | null;
     warn: (message: string) => void;
+    keyframeLocalization: boolean;
 }
 export declare const key: (value: unknown) => string;
 export declare function parseBlock(code: string, lang: Lang, options: ParseOptions): ParsedBlock;
@@ -85,6 +86,7 @@ export declare function addDeclarations(block: {
     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 overrideKey(rule: Rule): string;
 export declare function propertyOf(declaration: Declaration): {
     property: string;
     shorthand: boolean;

package/dist/compiler/block.js

@@ -1,6 +1,7 @@
 import { composeVisitors, transform } from 'lightningcss';
 import { atRuleInfo } from './at-rules.js';
 import { expand } from './expand.js';
+import { localizeKeyframes } from './keyframes.js';
 import { compose, fromPlaceholder, isElement, PLACEHOLDER, repair } from './selectors.js';
 import { splitBlock } from './split.js';
 import { SHORTHANDS } from '../shorthands.js';
@@ -82,11 +83,11 @@ 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));
-    return {
-        atoms: dropOverridden(parsed.atoms),
-        globals: parsed.globals,
-        composes: parsed.composes,
-    };
+    const atoms = dropOverridden(parsed.atoms);
+    if (!options.keyframeLocalization)
+        return { atoms, globals: parsed.globals, composes: parsed.composes };
+    const local = localizeKeyframes(parsed.globals);
+    return { atoms: local.atoms(atoms), globals: local.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.
@@ -276,11 +277,12 @@ export function addGlobal(rule, atRules, globals, position) {
     });
 }
 // The identity of an overridable at-rule: its type and name.
-function overrideKey(rule) {
+export function overrideKey(rule) {
     const value = valueOf(rule);
     switch (rule.type) {
         case 'keyframes':
-            return `keyframes ${key(value.name)}`;
+            // `@-webkit-keyframes x` doesn't replace `@keyframes x`.
+            return `keyframes ${key(value.vendorPrefix ?? [])} ${key(value.name)}`;
         case 'font-face': {
             // A font face is identified by its family, style, weight, and stretch.
             const descriptors = Object.fromEntries(value.properties

package/dist/compiler/compiler.d.ts

@@ -8,6 +8,7 @@ export type PrependFiles = string[] | {
 export interface Library {
     dir: string;
     prependFiles?: PrependFiles;
+    keyframeLocalization?: boolean;
 }
 export interface CompilerOptions {
     prependFiles?: PrependFiles;
@@ -17,6 +18,8 @@ export interface CompilerOptions {
     root?: string;
     warn?: (message: string) => void;
     quirksMode?: boolean;
+    keyframeLocalization?: boolean;
+    layer?: false | string;
 }
 export interface Block {
     code: string;

package/dist/compiler/compiler.js

@@ -1,9 +1,11 @@
 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 { print } from './print.js';
 import { lvhfaRank, withClass } from './selectors.js';
+import { KEYFRAMES_PREFIX } from './keyframes.js';
 import { MARKER_PREFIX, markerKey, parseStylesheet } from './stylesheet.js';
 const RANGES = {
     Digits: { start: '0030', end: '0039' },
@@ -45,14 +47,22 @@ export class Compiler {
     // most deeply nested library first.
     #prepend;
     #libraries;
+    // The layer the output is wrapped in, as parsed, or null for none.
+    #layer;
     #blocks = new Map();
     #stylesheets = new Map();
     #root;
-    // One name list for every class, and one for prefixes (the at-rules and
-    // selector variant a class is under), which only the `cn` table uses.
+    // One name list for every class, one for prefixes (the at-rules and
+    // selector variant a class is under), which only the `cn` table uses, and
+    // one for localized keyframes.
     #names;
-    // How often each class and prefix is used across scanned blocks.
-    #counts = { atoms: new Map(), prefixes: new Map() };
+    // How often each class, prefix, and localized keyframes is used across
+    // scanned blocks.
+    #counts = {
+        atoms: new Map(),
+        prefixes: new Map(),
+        keyframes: new Map(),
+    };
     #atoms = new Map();
     #globals = new Map();
     // The current global for each overridable at-rule.
@@ -63,14 +73,23 @@ export class Compiler {
         this.#names = {
             atoms: new SweatMap(options.quirksMode ? QUIRKS_NAME_OPTIONS : NAME_OPTIONS),
             prefixes: new SweatMap(NAME_OPTIONS),
+            // Keyframes names are case-sensitive, even in quirks mode. They reach
+            // four characters only after about 227,000 names, so they're never
+            // `none` or a CSS-wide keyword.
+            keyframes: new SweatMap(NAME_OPTIONS),
         };
+        this.#layer = layerRule(options.layer);
         const root = options.root ?? process.cwd();
         this.#root = root;
         this.#prepend = readPrepend(root, options.prependFiles);
         this.#libraries = (options.libraries ?? [])
             .map((library) => {
             const dir = resolvePath(root, library.dir);
-            return { dir: dir + sep, prepend: readPrepend(dir, library.prependFiles) };
+            return {
+                dir: dir + sep,
+                prepend: readPrepend(dir, library.prependFiles),
+                keyframeLocalization: library.keyframeLocalization ?? false,
+            };
         })
             .toSorted((a, b) => b.dir.length - a.dir.length);
         this.#parseOptions = {
@@ -90,17 +109,21 @@ export class Compiler {
         const parsed = this.#parse(block);
         this.#register(block, parsed);
         this.#count(this.#resolveBlock(block, parsed, []));
+        for (const global of parsed.globals)
+            this.#countKeyframes(global.key);
     }
     // Pass 1 of naming for a stylesheet file: counts what each class uses.
     scanStylesheet(sheet) {
         const parsed = this.#parseSheet(sheet);
         for (const name of parsed.classes.keys())
             this.#count(this.#resolveClass(sheet.file, parsed, name, [], []));
+        for (const global of parsed.globals)
+            this.#countKeyframes(global.key);
     }
     // Pass 2 of naming: gives the most-used entries the shortest names. Ties
     // are broken by key, so names don't depend on the order files are read.
     assignNames() {
-        for (const list of ['atoms', 'prefixes']) {
+        for (const list of ['atoms', 'prefixes', 'keyframes']) {
             const sorted = [...this.#counts[list]].toSorted(([a, countA], [b, countB]) => countB - countA || (a < b ? -1 : a > b ? 1 : 0));
             for (const [key] of sorted)
                 this.#names[list].set(key);
@@ -123,9 +146,9 @@ export class Compiler {
     // anything, for tools that only need the names (such as the TypeScript
     // content mapper).
     classNames(sheet) {
-        const { prepend } = this.#library(sheet.file);
+        const { options } = this.#library(sheet.file);
         try {
-            const parsed = parseStylesheet(sheet.code, sheet.lang, sheet.file, relative(this.#root, sheet.file), { ...this.#parseOptions, prepend });
+            const parsed = parseStylesheet(sheet.code, sheet.lang, sheet.file, relative(this.#root, sheet.file), options);
             return [...parsed.classes.keys()];
         }
         catch (error) {
@@ -160,8 +183,25 @@ export class Compiler {
             .filter((g) => g.global.hoist !== false)
             .toSorted((a, b) => a.global.hoist - b.global.hoist);
         const rest = globals.filter((g) => g.global.hoist === false);
-        const rules = [...hoisted, ...rest].map((g) => withLoc(g.global.key.includes(MARKER_KEY) ? this.#named(g.global.rule) : g.global.rule, loc(g.source)));
+        const named = (g) => withLoc(hasPlaceholder(g.global.key) ? this.#named(g.global.rule) : g.global.rule, loc(g.source));
+        let rules = [...hoisted, ...rest].map(named);
         rules.push(...this.#atomRules(loc));
+        // `@import` and `@namespace` can't be inside a layer, so they stay
+        // before it. `@layer` statements go inside, so the layers they order
+        // are the same ones blocks' `@layer` rules add to.
+        if (this.#layer !== null) {
+            rules = [
+                ...rules.filter(outside),
+                {
+                    type: 'layer-block',
+                    value: {
+                        ...valueOf(this.#layer),
+                        rules: rules.filter((r) => !outside(r)),
+                        loc: loc(null),
+                    },
+                },
+            ];
+        }
         return print(rules, sources, this.#parseOptions.lightningcss, this.#options.sourceMap ?? false);
     }
     // Classes on the element have an empty prefix.
@@ -177,19 +217,29 @@ export class Compiler {
         }
         return table;
     }
-    // A library's blocks and files get its prepended files instead of the
-    // app's.
+    // A library's blocks and files get its prepended files and keyframes
+    // setting instead of the app's.
     #library(file) {
         const library = file === undefined ? -1 : this.#libraries.findIndex(({ dir }) => file.startsWith(dir));
-        return { library, prepend: library === -1 ? this.#prepend : this.#libraries[library].prepend };
+        const { prepend, keyframeLocalization } = library === -1
+            ? { prepend: this.#prepend, keyframeLocalization: this.#options.keyframeLocalization }
+            : this.#libraries[library];
+        return {
+            library,
+            options: {
+                ...this.#parseOptions,
+                prepend,
+                keyframeLocalization: keyframeLocalization ?? false,
+            },
+        };
     }
     #parse(block) {
-        const { library, prepend } = this.#library(block.file);
+        const { library, options } = this.#library(block.file);
         const cacheKey = `${library}\n${block.lang}\n${block.code}`;
         let parsed = this.#blocks.get(cacheKey);
         if (parsed === undefined) {
             try {
-                parsed = parseBlock(block.code, block.lang, { ...this.#parseOptions, prepend });
+                parsed = parseBlock(block.code, block.lang, options);
             }
             catch (error) {
                 throw error instanceof PreStyleError ? locate(error, block) : error;
@@ -201,15 +251,12 @@ export class Compiler {
     // Parses a stylesheet file and registers its classes and global rules, so
     // the output includes them once the file is used.
     #parseSheet(sheet) {
-        const { library, prepend } = this.#library(sheet.file);
+        const { library, options } = this.#library(sheet.file);
         const cacheKey = `${library}\n${sheet.lang}\n${sheet.file}\n${sheet.code}`;
         let parsed = this.#stylesheets.get(cacheKey);
         if (parsed === undefined) {
             try {
-                parsed = parseStylesheet(sheet.code, sheet.lang, sheet.file, relative(this.#root, sheet.file), {
-                    ...this.#parseOptions,
-                    prepend,
-                });
+                parsed = parseStylesheet(sheet.code, sheet.lang, sheet.file, relative(this.#root, sheet.file), options);
             }
             catch (error) {
                 throw error instanceof PreStyleError ? locate(error, fileBlock(sheet.file)) : error;
@@ -301,6 +348,7 @@ export class Compiler {
             const prefix = prefixKey(atom);
             if (prefix !== '')
                 count(this.#counts.prefixes, prefix);
+            this.#countKeyframes(atom.declaration.key);
         }
         for (const extra of resolved.extras)
             if (extra.startsWith(MARKER_PREFIX))
@@ -312,7 +360,15 @@ export class Compiler {
             names.push(extra.startsWith(MARKER_PREFIX) ? this.#names.atoms.set(extra) : extra);
         return [...new Set(names)].join(' ');
     }
-    // Replaces markers in selectors with their names.
+    // Counts the localized keyframes a JSON key names.
+    #countKeyframes(json) {
+        if (!json.includes(KEYFRAMES_KEY))
+            return;
+        for (const [, hash] of json.matchAll(KEYFRAMES_KEY_RE))
+            count(this.#counts.keyframes, KEYFRAMES_PREFIX + hash);
+    }
+    // Replaces markers in selectors, and localized keyframes names, with their
+    // names.
     #named(value) {
         const visit = (node) => {
             if (Array.isArray(node))
@@ -324,6 +380,10 @@ export class Compiler {
                 typeof record.name === 'string' &&
                 record.name.startsWith(MARKER_PREFIX))
                 return { ...record, name: this.#names.atoms.set(record.name) };
+            if (record.type === 'ident' &&
+                typeof record.value === 'string' &&
+                record.value.startsWith(KEYFRAMES_PREFIX))
+                return { ...record, value: this.#names.keyframes.set(record.value) };
             return Object.fromEntries(Object.entries(record).map(([k, v]) => [k, visit(v)]));
         };
         return visit(value);
@@ -384,9 +444,12 @@ export class Compiler {
                     : [[{ 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: [atom.declaration.value] }
-                    : { declarations: [atom.declaration.value] };
+                    ? { importantDeclarations: [value] }
+                    : { declarations: [value] };
                 return {
                     type: 'style',
                     value: { selectors, declarations, rules: [], loc: loc(source) },
@@ -403,8 +466,40 @@ export class Compiler {
         return emit(root);
     }
 }
-// Markers as they appear in JSON keys, which escape the `\0`.
+// Markers and localized keyframes names as they appear in JSON keys, which
+// escape the `\0`.
 const MARKER_KEY = JSON.stringify(MARKER_PREFIX).slice(1, -1);
+const KEYFRAMES_KEY = JSON.stringify(KEYFRAMES_PREFIX).slice(1, -1);
+const KEYFRAMES_KEY_RE = new RegExp(`${RegExp.escape(KEYFRAMES_KEY)}([\\w-]+)`, 'g');
+// Rules that can't be inside a layer.
+const outside = (rule) => rule.type === 'import' || rule.type === 'namespace';
+const hasPlaceholder = (json) => json.includes(MARKER_KEY) || json.includes(KEYFRAMES_KEY);
+// Parses the `layer` option into an `@layer` block rule.
+function layerRule(layer) {
+    if (layer === undefined || layer === false)
+        return null;
+    if (typeof layer !== 'string')
+        throw new PreStyleError('`layer` must be `false` or a string.', null);
+    let rule;
+    try {
+        transform({
+            filename: 'layer.css',
+            code: Buffer.from(`@layer ${layer} {}`),
+            visitor: {
+                StyleSheetExit(sheet) {
+                    if (sheet.rules.length === 1)
+                        rule = sheet.rules[0];
+                },
+            },
+        });
+    }
+    catch {
+        // Reported below.
+    }
+    if (rule?.type !== 'layer-block' || (layer.trim() === '') !== (rule.value.name == null))
+        throw new PreStyleError(`\`layer\` must be a layer name, such as "pre.style" or "base.components", or "" for an unnamed layer. Got ${JSON.stringify(layer)}.`, null);
+    return rule;
+}
 // A stylesheet file, for positions and source maps.
 const fileBlock = (file) => ({ code: '', lang: 'css', file, line: 1, column: 1 });
 // Reads prepended files, relative to `dir`, once.

package/dist/compiler/config.d.ts

@@ -6,6 +6,7 @@ export interface PackageConfig {
     prependFiles?: PrependFiles;
     libraries?: Record<string, LibraryConfig | boolean>;
     quirksMode?: boolean;
+    keyframeLocalization?: boolean;
 }
 export declare function checkField(field: Record<string, unknown>, where: string, keys: Set<string>): string[];
 export declare function readConfig(root: string): {

package/dist/compiler/config.js

@@ -1,6 +1,13 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
-const KEYS = new Set(['include', 'exclude', 'prependFiles', 'libraries', 'quirksMode']);
+const KEYS = new Set([
+    'include',
+    'exclude',
+    'prependFiles',
+    'libraries',
+    'quirksMode',
+    'keyframeLocalization',
+]);
 const isStrings = (value) => typeof value === 'string' ||
     (Array.isArray(value) && value.every((item) => typeof item === 'string'));
 const isPrependFiles = (value) => (Array.isArray(value) && isStrings(value)) ||
@@ -22,6 +29,8 @@ export function checkField(field, where, keys) {
         fail('prependFiles', 'an array of paths, or an object with `css` and `scss` arrays');
     if (field.quirksMode !== undefined && typeof field.quirksMode !== 'boolean')
         fail('quirksMode', '`true` or `false`');
+    if (field.keyframeLocalization !== undefined && typeof field.keyframeLocalization !== 'boolean')
+        fail('keyframeLocalization', '`true` or `false`');
     if (field.libraries !== undefined &&
         (field.libraries === null ||
             typeof field.libraries !== 'object' ||

package/dist/compiler/keyframes.d.ts

@@ -0,0 +1,6 @@
+import type { Atom, GlobalRule } from './block.ts';
+export declare const KEYFRAMES_PREFIX = "\0pre.style-keyframes:";
+export declare function localizeKeyframes(globals: GlobalRule[]): {
+    globals: GlobalRule[];
+    atoms: (atoms: Atom[]) => Atom[];
+};

package/dist/compiler/keyframes.js

@@ -0,0 +1,120 @@
+import { createHash } from 'node:crypto';
+import { 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
+// the name in its scope (a block, or a stylesheet file), so identical
+// keyframes share a name wherever they're defined. The compiler gives it a
+// name when printing.
+export const KEYFRAMES_PREFIX = '\0pre.style-keyframes:';
+// Properties whose values name keyframes, without a vendor prefix.
+const ANIMATION_PROPERTIES = new Set(['animation', 'animation-name']);
+// Replaces each `@keyframes` name defined in a scope (in its globals, which
+// include its prepended code) with a local name, in the definitions, and,
+// through `atoms`, in `animation` and `animation-name` declarations. Names
+// the scope doesn't define are left as they are.
+export function localizeKeyframes(globals) {
+    const definitions = new Map();
+    for (const global of globals)
+        eachKeyframes(global.rule, (value) => {
+            const list = definitions.get(value.name.value) ?? [];
+            list.push(key({ vendorPrefix: value.vendorPrefix, keyframes: value.keyframes }));
+            definitions.set(value.name.value, list);
+        });
+    if (definitions.size === 0)
+        return { globals, atoms: (atoms) => atoms };
+    const local = new Map();
+    for (const [name, list] of definitions)
+        local.set(name, KEYFRAMES_PREFIX +
+            createHash('sha256').update(JSON.stringify(list)).digest('base64url').slice(0, 16));
+    return {
+        globals: globals.map((global) => {
+            let found = false;
+            const rule = mapRule(global.rule, (inner) => {
+                if (inner.type !== 'keyframes')
+                    return inner;
+                found = true;
+                const value = valueOf(inner);
+                return {
+                    ...inner,
+                    value: {
+                        ...value,
+                        name: { type: 'ident', value: local.get(value.name.value) },
+                    },
+                };
+            });
+            if (!found)
+                return global;
+            return {
+                ...global,
+                key: key(rule),
+                rule,
+                overrideKey: global.overrideKey === null ? null : overrideKey(rule),
+            };
+        }),
+        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)
+                return atom;
+            return {
+                ...atom,
+                declaration: {
+                    ...atom.declaration,
+                    key: key(value) + (atom.declaration.important ? '!' : ''),
+                    value,
+                },
+            };
+        }),
+    };
+}
+// Calls `visit` for each `@keyframes` rule in a rule, including inside the
+// at-rules a global keeps around it.
+function eachKeyframes(rule, visit) {
+    mapRule(rule, (inner) => {
+        if (inner.type === 'keyframes')
+            visit(valueOf(inner));
+        return inner;
+    });
+}
+// Maps a rule and the rules nested in it.
+function mapRule(rule, map) {
+    const value = valueOf(rule);
+    const mapped = Array.isArray(value.rules)
+        ? {
+            ...rule,
+            value: {
+                ...value,
+                rules: value.rules.map((r) => mapRule(r, map)),
+            },
+        }
+        : rule;
+    return map(mapped);
+}
+// Replaces names in idents and strings (parsed animation names, and tokens
+// in unparsed values). Returns `value` itself when nothing changed.
+function renameIdents(value, local) {
+    const visit = (node) => {
+        if (Array.isArray(node)) {
+            const mapped = node.map(visit);
+            return mapped.some((item, i) => item !== node[i]) ? mapped : node;
+        }
+        if (node === null || typeof node !== 'object')
+            return node;
+        const record = node;
+        if ((record.type === 'ident' || record.type === 'string') &&
+            typeof record.value === 'string' &&
+            local.has(record.value))
+            return { type: 'ident', value: local.get(record.value) };
+        let changed = false;
+        const entries = Object.entries(record).map(([k, v]) => {
+            const mapped = visit(v);
+            if (mapped !== v)
+                changed = true;
+            return [k, mapped];
+        });
+        return changed ? Object.fromEntries(entries) : node;
+    };
+    return visit(value);
+}

package/dist/compiler/libraries.d.ts

@@ -3,6 +3,7 @@ export interface LibraryConfig {
     include?: string | string[];
     exclude?: string | string[];
     prependFiles?: PrependFiles;
+    keyframeLocalization?: boolean;
 }
 export interface ResolvedLibrary {
     name: string;
@@ -10,5 +11,6 @@ export interface ResolvedLibrary {
     include: string[];
     exclude: string[];
     prependFiles?: PrependFiles;
+    keyframeLocalization?: boolean;
 }
 export declare function findLibraries(root: string, overrides?: Record<string, LibraryConfig | boolean>, warn?: (message: string) => void): ResolvedLibrary[];

package/dist/compiler/libraries.js

@@ -3,7 +3,7 @@ import { dirname, join } from 'node:path';
 import { checkField } from './config.js';
 // Keys a library's field shares with the app's. `libraries` and
 // `quirksMode` only apply to the app.
-const SHARED_KEYS = new Set(['include', 'exclude', 'prependFiles']);
+const SHARED_KEYS = new Set(['include', 'exclude', 'prependFiles', 'keyframeLocalization']);
 const APP_KEYS = new Set(['libraries', 'quirksMode']);
 const DEFAULT_INCLUDE = ['**/*.{js,jsx,ts,tsx,mjs,cjs,mts,cts,astro}'];
 const readPackage = (dir) => JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8'));
@@ -44,13 +44,14 @@ export function findLibraries(root, overrides = {}, warn = () => { }) {
             for (const warning of checkField(config, where, new Set([...SHARED_KEYS, ...APP_KEYS])))
                 warn(warning);
         }
-        const { include, exclude, prependFiles } = config === true ? {} : config;
+        const { include, exclude, prependFiles, keyframeLocalization } = config === true ? {} : config;
         libraries.push({
             name,
             dir,
             include: include === undefined ? DEFAULT_INCLUDE : [include].flat(),
             exclude: exclude === undefined ? [] : [exclude].flat(),
             prependFiles,
+            keyframeLocalization,
         });
         // A library's peer dependencies are installed by the app, and found the
         // same way from the library.

package/dist/compiler/mapper.js

@@ -29,8 +29,13 @@ async function openProject(params) {
     const compiler = createCompiler({
         root: app.dir,
         prependFiles: app.config.prependFiles,
-        libraries: libraries.map(({ dir, prependFiles }) => ({ dir, prependFiles })),
+        libraries: libraries.map(({ dir, prependFiles, keyframeLocalization }) => ({
+            dir,
+            prependFiles,
+            keyframeLocalization,
+        })),
         quirksMode: app.config.quirksMode,
+        keyframeLocalization: app.config.keyframeLocalization,
         warn: () => { },
     });
     projects.set(params.projectHandle, compiler);

package/dist/compiler/stylesheet.js

@@ -1,6 +1,7 @@
 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 { localizeKeyframes } from './keyframes.js';
 import { compose, isElement } from './selectors.js';
 // Classes used as context for another class (`.card:hover .title`), or in a
 // compound with it (`.a.b`), are replaced with a marker: one generated name
@@ -144,6 +145,13 @@ export function parseStylesheet(code, lang, file, id, options) {
     }
     for (const target of classes.values())
         target.atoms = dropOverridden(target.atoms);
+    // Keyframes are local to the whole file, as in CSS Modules.
+    if (options.keyframeLocalization) {
+        const local = localizeKeyframes(parsed.globals);
+        parsed.globals = local.globals;
+        for (const target of classes.values())
+            target.atoms = local.atoms(target.atoms);
+    }
     return parsed;
 }
 // Flattens rules into entries, in order: style rules with their full

package/package.json

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

package/package.schema.json

@@ -60,6 +60,10 @@
         },
         "prependFiles": {
           "$ref": "#/definitions/prependFiles"
+        },
+        "keyframeLocalization": {
+          "description": "Give each @keyframes in the library's blocks and stylesheet files a generated name, used only in the block or file that defines it, like styled-components' `keyframes`. The app's setting doesn't apply to libraries.",
+          "type": "boolean"
         }
       }
     }
@@ -84,6 +88,10 @@
         "prependFiles": {
           "$ref": "#/definitions/prependFiles"
         },
+        "keyframeLocalization": {
+          "description": "Give each @keyframes in the app's blocks and stylesheet files a generated name, used only in the block or file that defines it (including keyframes from prepended files), like styled-components' `keyframes`. Libraries use their own setting.",
+          "type": "boolean"
+        },
         "libraries": {
           "description": "App only. 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.",
           "type": "object",