@navecss/core 0.5.0 → 0.6.0

package/README.md

@@ -182,7 +182,7 @@ without a new warning, it says what to move, and it always shows how to mark the
 directive if the later value is meant to win:
 
 ```text
-src/panel.css:3:3: @nave: display: grid comes after "hideDesktopUp", so under @media (width >= 75em) display is grid, not none. Before @navecss/core 0.5.0 "hideDesktopUp" won, because an atom's blocks were placed last in the rule. To let "hideDesktopUp" win, move display: grid above the directive. If it is meant to win, mark the directive that names "hideDesktopUp": `@nave /* nave-allow-override: display */ hideDesktopUp;`
+src/panel.css:3:3: @nave: display: grid comes after "hideDesktopUp", so under @media (width >= 75em) display is grid, not none. To let "hideDesktopUp" win, move display: grid above the directive. If it is meant to win, mark the directive that names "hideDesktopUp": `@nave /* nave-allow-override: display */ hideDesktopUp;`
 ```
 
 Where no move clears the warning, as when the later value comes from another atom's
@@ -198,8 +198,7 @@ changing its exit code. No option turns it off for the whole project.
 A directive written inside a nested rule that applies to the same element, such as
 `.card { & { @nave hideDesktopUp } display: flex; }`, is checked the same way: its atoms' blocks
 are compared with what follows the directive inside that nested rule, and with what each
-enclosing rule holds after the nested rule. A warning of the second kind says nothing about
-earlier releases, because that later content already won in them.
+enclosing rule holds after the nested rule.
 
 **Marking an override you mean.** Name the property in a comment inside the
 directive:
@@ -326,7 +325,9 @@ Every custom property Nave declares is in the stylesheet you already installed,
 
 On Vite, use the Vite plugin: it is the one route this package teaches for Vite, and for Astro,
 which builds with Vite ([Astro](#astro) has its config). On
-Next.js, webpack, or any other pipeline that runs PostCSS plugins, use the PostCSS plugin. A host
+Next.js, use [`@navecss/prune`](https://github.com/navecss/navecss/tree/main/packages/prune#readme)
+to ship only the atoms the build can read a use for, or the PostCSS plugin to keep every atom. On
+webpack, or any other pipeline that runs PostCSS plugins, use the PostCSS plugin. A host
 that runs Lightning CSS directly uses [the Lightning CSS adapter](#lightning-css-adapter-setup),
 and a project with no bundler uses [`navecss-core expand`](#navecss-core-expand).
 
@@ -594,16 +595,27 @@ list: with an empty list, or none, it fails the build. Each client build records
 `nave-used-atoms.json` file described below, the atoms it read from each listed package's calls,
 where the calls it could not read are, and any `keepFor` key that names no package the build read.
 
-`keepFor` stands in for the package's own calls, never for a call your code makes, so three problems
+`keepFor` stands in for the package's own calls, never for a call your code makes, so four problems
 in a listed package still fail the build. A module of the package that re-exports `cx` under the
 name `cx` still fails when a file of yours imports `cx` from that module itself, in an `import` or
 `export ... from` statement, or a dependency that does more than re-export it imports it from there,
 and the report gives the `cxModules` entry that lets the build read those calls. Through a module
 that only re-exports it, such as the package's own entry file or another package, a listed module
 would be two steps away, so there the report names each file of yours that takes it: import `cx`
-from `@navecss/core/cx` there instead. A module that gives `cx` out under another name, as a default
-or inside a namespace, still fails when your code takes that export, and the report names each file
-of yours that does: import `cx` from `@navecss/core/cx` there instead. And a module of the package
+from `@navecss/core/cx` there instead. A CommonJS module that forwards it with
+`module.exports = require(...)` or `exports.cn = require(...).cn`, or with what TypeScript emits for
+`export { cn } from` and `export * from` when it compiles to CommonJS, counts as one that only
+re-exports it. A module that gives `cx` out under another name, as a default
+or inside a namespace, or by assigning it first (`export const cn = cx`), still fails when your code
+takes that export, and the report names each file of yours that does: import `cx` from
+`@navecss/core/cx` there instead. A module of the package that uses `cx` where the build cannot
+follow it to an export, such as `obj.cn = cx`, `memo(cx)` or `{ cn: cx }`, or that takes a module
+holding a `cx` export in a way the build reads neither as calls only nor as a forward,
+such as the CommonJS that Babel, esbuild or Rollup write for `export * from`, fails whenever it is
+part of the build, whatever your code takes from the package, because the build cannot tell whether
+a call of yours goes through it. The report names the file and the form. The fix is the package's,
+in a release of it or a patched copy: export `cx` by name from an ES module. Until then, ship every
+atom (below). And a module of the package
 that you list in `cxModules` but that does not re-export Nave's `cx` under that name still fails:
 remove it from `cxModules`.
 
@@ -619,6 +631,11 @@ A class your code takes at run time from `@navecss/core/atoms` (`atomClassMap[va
 `toClassName('grid')`) is one the build does not read: it neither reads nor refuses it, so list its
 atom in `keep`.
 
+A package listed in `keepFor` can give `cx` to your code without the build failing if it redefines
+or adds a method on `Function.prototype` or `Object.prototype`, or declares its own function under
+one of the names compilers reserve for their interop helpers, such as `__importStar`: the build
+cannot see either.
+
 If your pages are rendered outside the build, by a backend that serves its own templates and uses
 Vite for its assets only, the build reads none of their classes. While `keep` is empty, the plugin
 warns when it has read no HTML page, no server render and no use of Nave at all: no `cx()` call, no
@@ -628,7 +645,9 @@ templates use in `keep`, or, if they are many, ship every atom (below).
 
 The PostCSS plugin and the Lightning CSS adapter read no `cx()` call and leave every atom in the
 layer, on Next.js and webpack alike; so does a page with no bundler, which links the standalone
-stylesheet.
+stylesheet. On Next.js,
+[`@navecss/prune`](https://github.com/navecss/navecss/tree/main/packages/prune#readme) ships only
+the atoms its build can read a use for.
 
 A server build leaves packages in `node_modules` external by default, so it does not read their
 code. For such a package that depends on `@navecss/core`, the build warns, naming it, unless it is
@@ -806,6 +825,10 @@ If you are using only `cx()` or tokens, you do not need to install it.
 
 #### Next.js
 
+To ship only the atoms the build can read a use for, use
+[`@navecss/prune`](https://github.com/navecss/navecss/tree/main/packages/prune#readme) in place of
+this plugin. The setup below keeps every atom.
+
 Next.js reads a PostCSS plugin by its package name, so give it the name as a key and do not
 call `navePlugin()`:
 
@@ -1134,3 +1157,9 @@ Consumers of `@navecss/tokens` alone get no guide: it ships only in this package
 | `@navecss/core/postcss`      | PostCSS plugin — `navePlugin()`                                                                                   |
 | `@navecss/core/check`        | The survival check as a function — `check({ source })`                                                            |
 | `@navecss/core/collect`      | Reads which atoms a module uses and trims the atom layer to them, for build tools; not meant for application code |
+
+## Trademark
+
+This package is not affiliated with, endorsed by or sponsored by Vercel or the Next.js project.
+
+Vercel, the Vercel design, Next.js and related marks, designs and logos are trademarks or registered trademarks of Vercel, Inc. or its affiliates in the US and other countries.

package/dist/bin.js

@@ -1,11 +1,11 @@
 #!/usr/bin/env node
 import { runCheck } from './chunk-CTFEYJBE.js';
 import { splitByteOrderMark } from './chunk-2TNTYI4L.js';
-import { foldedText, orderWarningTexts } from './chunk-KKUYU75D.js';
+import { foldedText, orderWarningTexts } from './chunk-R6R5DSTT.js';
 import { formatFinding } from './chunk-ZNTNLGEC.js';
-import { validateExtendAtomsHostFree } from './chunk-63H2FLGU.js';
+import { validateExtendAtomsHostFree } from './chunk-B5CWZIBK.js';
 import { resolveExtendSpecifier, applyExtendModule } from './chunk-NKUZNRF4.js';
-import { snapshotExtendMap, expandText } from './chunk-MWHZ26S4.js';
+import { snapshotExtendMap, expandText } from './chunk-KDLLTOAM.js';
 import { createPositionFinder, atKeywordName } from './chunk-UVHGEVMV.js';
 import './chunk-SYNQJNVB.js';
 import './chunk-CUL5PLPI.js';

package/dist/{chunk-63H2FLGU.js → chunk-B5CWZIBK.js}

@@ -1,4 +1,4 @@
-import { walkExtendAtoms, hasEscapedCommentOpener, isOnlyInert, hasTopLevelComment, hasUnstrippedTrailingSpace, hasUnstrippedLeadingSpace, lastNonWhitespace, isInert, hasPaddedComment, hasBrokenString, hasUrl, hasStrayCurlyCloser, anchorSelectorList, hasEscapedWhitespace, hasHtmlBreakout, hasTopLevelColon } from './chunk-MWHZ26S4.js';
+import { walkExtendAtoms, hasEscapedCommentOpener, isOnlyInert, hasTopLevelComment, hasUnstrippedTrailingSpace, hasUnstrippedLeadingSpace, lastNonWhitespace, isInert, hasPaddedComment, hasBrokenString, hasUrl, hasStrayCurlyCloser, anchorSelectorList, hasEscapedWhitespace, hasHtmlBreakout, hasTopLevelColon } from './chunk-KDLLTOAM.js';
 import { matchBrackets, readItem } from './chunk-UVHGEVMV.js';
 import { tokenize } from './chunk-2K5EBBF2.js';