@navecss/core 0.3.0 → 0.5.0

package/dist/collect.d.ts

@@ -0,0 +1,317 @@
+export { R as ResolvedUsedOptions, U as UsedAtomOptions, a as assertOptions, k as keptAtoms, r as resolveUsedOptions } from './vite-options-sOCeGn9B.js';
+import './atom-names-B8Ud-7zD.js';
+
+/**
+ * The few shapes of the ESTree `this.parse` returns that the collector reads, declared here
+ * rather than imported: the plugin takes no dependency, and a node is read through a handful of
+ * typed accessors instead of a full ESTree type package.
+ */
+interface AstNode {
+    readonly type: string;
+    readonly start: number;
+    readonly end: number;
+    readonly [key: string]: unknown;
+}
+
+/**
+ * One thing the collector could not read in a module, before it has a position or a path: what
+ * it is, where it starts (an offset into the module as the post-order half saw it), the
+ * construct as the plugin reads it, and the sentence that follows the construct in the report.
+ */
+/**
+ * The kinds a report groups its remedy lines by; the order here is the order the lines print.
+ */
+declare const PROBLEM_KINDS: readonly ["argument", "reference", "reexport", "declared", "concatenation", "dynamic", "unknown", "own", "unreadable"];
+type ProblemKind = (typeof PROBLEM_KINDS)[number];
+interface Problem {
+    readonly kind: ProblemKind;
+    readonly offset: number;
+    /**
+     * The construct, quoted as the plugin reads it, before it is cut for the report.
+     */
+    readonly construct: string;
+    /**
+     * The sentence after the construct.
+     */
+    readonly text: string;
+    /**
+     * For an unknown atom with no near candidate: the report closes with `Available:`.
+     */
+    readonly needsAvailable?: boolean;
+    /**
+     * For a re-export: whether listing the module in `cxModules` would clear it, which it does not
+     * when the module re-exports the `cx` of a module that is already listed (a second hop).
+     */
+    readonly isListable?: boolean;
+    /**
+     * For a re-export of Nave's `cx`: whether it gives `cx` under a name other than `cx`, as a default
+     * or inside a namespace. A listed module may not do that, so listing the module would only turn
+     * this problem into another one: no `cxModules` entry clears it.
+     */
+    readonly isRenamed?: boolean;
+    /**
+     * For a problem that gives Nave's `cx` out of its module, or a namespace holding it, or the `cx`
+     * of a module listed in `cxModules`: the names it is exported under (`default` for the default
+     * export), so a build-end check can tell whether an importer takes it.
+     */
+    readonly exportedAs?: readonly string[];
+    /**
+     * For a problem in a module listed in `cxModules`: whether the module also exports Nave's own
+     * `cx`. An importer's `cx` is then Nave's, so what the build says of its calls is not an echo of
+     * this problem and stays when the problem is reported.
+     */
+    readonly hasNaveCx?: boolean;
+}
+
+/**
+ * Replaces the text from `start` up to `end` of the module with `text`.
+ */
+interface Edit {
+    readonly start: number;
+    readonly end: number;
+    readonly text: string;
+}
+
+/**
+ * What a compiled Vue component's script exposes to its template, and how a template reads it:
+ * `$setup.<name>`.
+ */
+
+type SetupExposure = {
+    readonly kind: 'cx';
+} | {
+    readonly kind: 'values';
+    readonly values: readonly string[];
+};
+type SetupExposures = ReadonlyMap<string, SetupExposure>;
+
+interface ReadOptions {
+    /**
+     * The import specifiers that bind Nave's `cx`: its own module, and every module listed in
+     * `cxModules` that this module imports.
+     */
+    readonly cxSources: ReadonlySet<string>;
+    /**
+     * The specifiers in `cxSources` that name a module listed in `cxModules`.
+     */
+    readonly declaredSources?: ReadonlySet<string>;
+    /**
+     * Whether this module is itself listed in `cxModules`, so its exports of `cx` are judged as a
+     * listed module's.
+     */
+    readonly isDeclared?: boolean;
+    /**
+     * The names of the consumer's own atoms, which have no class.
+     */
+    readonly ownAtoms: ReadonlySet<string>;
+    /**
+     * Whether this module belongs to a dependency, where a Nave class built from pieces is only
+     * refused if the module also imports `cx`.
+     */
+    readonly isDependency: boolean;
+    /**
+     * For a compiled Vue template: what its component's script exposes to it.
+     */
+    readonly setup?: SetupExposures | undefined;
+    /**
+     * Whether the module is a compiled Vue component's `<script setup>`.
+     */
+    readonly isVueScript?: boolean;
+    /**
+     * Set in a build: the reading also returns the edits that turn each call it read into the
+     * string the call returns, and `keep` is the map a `cx.dynamic()` call looks a name up in.
+     */
+    readonly rewrite?: {
+        readonly keep: Readonly<Record<string, string>>;
+    };
+}
+interface ModuleReading {
+    /**
+     * Built-in atoms named by a readable `cx()` call.
+     */
+    readonly atoms: Set<string>;
+    /**
+     * Built-in atoms whose class is written whole in the module.
+     */
+    readonly classes: Set<string>;
+    readonly problems: Problem[];
+    /**
+     * Where `cx.dynamic()` is called, and the call as the plugin reads it.
+     */
+    readonly dynamicCalls: {
+        readonly construct: string;
+        readonly offset: number;
+    }[];
+    /**
+     * For a compiled Vue `<script setup>`: what it exposes to its template.
+     */
+    readonly exposes: Map<string, SetupExposure>;
+    /**
+     * Whether the module imports from a `cx` source, whether or not it uses the import.
+     */
+    readonly usesCx: boolean;
+    /**
+     * With `rewrite` set: the edits that replace the calls the reading found, empty otherwise.
+     */
+    readonly edits: Edit[];
+}
+
+/**
+ * Reads one module for the atoms its `cx()` calls and written classes name, and for everything
+ * in it the build cannot read. Pure: it takes the parsed module and returns what it found, so the
+ * host (the post-order plugin) decides where the findings go.
+ */
+
+declare const CX_SOURCE = "@navecss/core/cx";
+
+/**
+ * Reads `program`, the parse of `code`.
+ */
+declare function readModule(code: string, program: AstNode, options: ReadOptions): ModuleReading;
+
+interface LayerReading {
+    /**
+     * Whether the stylesheet holds an `@layer atomic { ... }` block.
+     */
+    readonly hasLayer: boolean;
+    /**
+     * The built-in atoms whose class a rule in the layer selects.
+     */
+    readonly atoms: Set<string>;
+}
+/**
+ * `css` with every rule in an `@layer atomic` block that needs an atom outside `emitted` removed.
+ */
+declare function pruneAtomicLayer(css: string, emitted: ReadonlySet<string>): string;
+/**
+ * What the `@layer atomic` blocks of `css` hold.
+ */
+declare function inspectAtomicLayer(css: string): LayerReading;
+/**
+ * The atoms outside `emitted` that a rule left in the `@layer atomic` blocks of `css` still needs
+ * an element of: what a pruning to `emitted` would still remove, sorted.
+ */
+declare function unprunedAtoms(css: string, emitted: ReadonlySet<string>): string[];
+
+/**
+ * `atoms` with the atoms added that restore what an atom in it removes: `srOnlyFocusable` shows
+ * again on focus what `srOnly` hides, so a set that holds `srOnly` holds it too. This adds to the
+ * emitted set only, not to `keep` or to what `cx.dynamic()` accepts.
+ */
+declare function withRestorers(atoms: Set<string>): Set<string>;
+
+/**
+ * What an importer takes from a module that gives out Nave's `cx`: which of its `cx` exports it
+ * imports, re-exports or reads off a namespace. The test is by name, not by file: an importer that
+ * takes only `Button` from a module which also exports `cx` as `cn` takes no `cx` from it, so
+ * nothing of its own routes calls through `cn`. A take the parse cannot tell apart (a namespace
+ * passed on, a computed key, a rest element, an `import()` used any other way) counts as taken, and
+ * so does an importer whose text names the module in no way the build reads (a `require()`).
+ */
+
+/**
+ * How an importer takes the module: by the names it imports or re-exports, as a namespace, as
+ * `export *`, as an `import()`, or in a way the build cannot read.
+ */
+type TakeShape = 'dynamic-import' | 'names' | 'namespace' | 'star' | 'unreadable';
+interface Taken {
+    readonly shape: TakeShape;
+    /**
+     * The `cx` exports the importer takes by name; none when it takes the module whole.
+     */
+    readonly names: readonly string[];
+    /**
+     * Whether the importer only passes on what it takes: a named re-export, or an import that it
+     * then exports.
+     */
+    readonly isPassedOn?: boolean;
+    /**
+     * Whether the importer does nothing with what it takes but re-export it: `export ... from`, or an
+     * import that every use of is an export. A forward is followed to what takes it; it is not a
+     * take on the `cxModules` route.
+     */
+    readonly isForward?: boolean;
+    /**
+     * Whether the take comes from what an earlier server command left in the cache directory.
+     */
+    readonly isRecorded?: boolean;
+}
+interface Take extends Taken {
+    /**
+     * The importer's path, relative to the project root, with forward slashes.
+     */
+    readonly taker: string;
+    /**
+     * Whether the module taken from is reached through another module of its package, which
+     * re-exports the `cx` it gives out.
+     */
+    readonly isReached: boolean;
+}
+
+/**
+ * The report a build fails with when it meets a use it cannot read: a first line counting the
+ * problems and stating the cause, one line per problem with a 1-based, root-relative position,
+ * and the remedy block printed once, last. Under the default nobody set the option, so the first
+ * line never names it, and no remedy printed for application code is `atomic: 'all'`: an agent
+ * takes the first remedy that clears the error, and that one always does.
+ */
+
+interface LocatedProblem extends Problem {
+    /**
+     * The module's path, relative to the project root, with forward slashes.
+     */
+    readonly file: string;
+    readonly line: number;
+    readonly column: number;
+    /**
+     * Set when the source map does not lead to the authored position: `line` and `column` are then
+     * zero and mean nothing, and this is the sentence that ends the problem's line.
+     */
+    readonly unknownLine?: string | undefined;
+    /**
+     * The package name when the module lies under `node_modules`.
+     */
+    readonly pkg?: string | undefined;
+    /**
+     * The id of the module the problem is in, for a problem the build-end check looks into the
+     * module graph for.
+     */
+    readonly moduleId?: string | undefined;
+    /**
+     * For a dependency's re-export of `cx`: the specifier that resolves from the project root to the
+     * module that holds it, when a `cxModules` entry can name it.
+     */
+    readonly specifier?: string | undefined;
+    /**
+     * For a dependency's listed module that exports a `cx` the build does not follow: the
+     * `cxModules` entries, as written, that name it.
+     */
+    readonly entries?: readonly string[] | undefined;
+    /**
+     * For a module of a package `keepFor` lists that gives `cx` out under another name: the
+     * application modules that take one of its `cx` exports, which `keepFor` does not clear.
+     */
+    readonly takes?: readonly Take[] | undefined;
+    /**
+     * For a dependency module that re-exports the `cx` of a module `cxModules` lists: the modules of
+     * other dependencies that call through it, root-relative, which only the package's `keepFor`
+     * entry can stand in for.
+     */
+    readonly callers?: readonly string[] | undefined;
+}
+declare const REPORT_CAUSE = "the build cannot tell which atoms these apply, and it ships only the atoms it can read.";
+/**
+ * The remedy lines only a host can write, given the application's problems: they print after the
+ * lines of the application's kinds and before any package's line.
+ */
+type HostRemedies = (application: readonly LocatedProblem[]) => readonly string[];
+/**
+ * The build report for every problem of an environment. `configured` is the `cxModules` list the
+ * remedies that print one extend, and `home` is how the host spells where the options are written,
+ * the call of its plugin or its wrapper: the one place the report names its host. `hostRemedies`
+ * adds the lines only the host can write.
+ */
+declare function buildReport(problems: readonly LocatedProblem[], configured: readonly string[], home: string, hostRemedies?: HostRemedies): string;
+
+export { CX_SOURCE, REPORT_CAUSE, buildReport, inspectAtomicLayer, pruneAtomicLayer, readModule, unprunedAtoms, withRestorers };
+export type { AstNode, HostRemedies, LayerReading, LocatedProblem, ModuleReading, Problem, ProblemKind, ReadOptions };

package/dist/collect.js

@@ -0,0 +1,5 @@
+export { CX_SOURCE, REPORT_CAUSE, assertOptions, buildReport, inspectAtomicLayer, keptAtoms, pruneAtomicLayer, readModule, resolveUsedOptions, unprunedAtoms, withRestorers } from './chunk-BCUK4M4P.js';
+import './chunk-SYNQJNVB.js';
+import './chunk-CUL5PLPI.js';
+import './chunk-2K5EBBF2.js';
+import './chunk-GZL2VW7C.js';

package/dist/css.d.ts

@@ -0,0 +1 @@
+export {}

package/dist/cx.d.ts

@@ -1,4 +1,4 @@
-import { AtomName } from './atoms.js';
+import { A as AtomName } from './atom-names-B8Ud-7zD.js';
 
 /**
  * cx — typed atomic class composer for Nave.

package/dist/cx.js

@@ -1,12 +1,25 @@
-import { atomClassMap } from './chunk-LIUB4EES.js';
+import { atomClassMap } from './chunk-GZL2VW7C.js';
 
 // src/cx.ts
+var decodedKeep = /* @__PURE__ */ new Map();
+function decodedMap(text) {
+  let map = decodedKeep.get(text);
+  if (map === void 0) {
+    map = JSON.parse(text);
+    decodedKeep.set(text, map);
+  }
+  return map;
+}
 var cx = (...args) => args.filter(Boolean).map(
   (arg) => Object.hasOwn(atomClassMap, arg) ? atomClassMap[arg] : arg
 ).join(" ");
 cx.raw = (...args) => args.filter(Boolean).join(" ");
 cx.dynamic = (name) => {
   if (!name) return "";
+  if (typeof __NAVE_KEEP_CLASSES__ === "string") {
+    const decoded = decodedMap(__NAVE_KEEP_CLASSES__);
+    return Object.hasOwn(decoded, name) ? decoded[name] ?? "" : "";
+  }
   const map = typeof __NAVE_KEEP_CLASSES__ === "undefined" ? atomClassMap : __NAVE_KEEP_CLASSES__;
   return Object.hasOwn(map, name) ? map[name] : "";
 };

package/dist/lightningcss.d.ts

@@ -1,4 +1,5 @@
 import { AtomDefinition } from './atoms.js';
+import './atom-names-B8Ud-7zD.js';
 
 interface NaveLightningOptions {
     /**
@@ -47,4 +48,5 @@ interface NaveLightningAdapter {
  */
 declare function navePlugin(options?: NaveLightningOptions): NaveLightningAdapter;
 
-export { type NaveLightningAdapter, type NaveLightningOptions, navePlugin as default, navePlugin };
+export { navePlugin as default, navePlugin };
+export type { NaveLightningAdapter, NaveLightningOptions };

package/dist/lightningcss.js

@@ -1,8 +1,12 @@
-import { splitByteOrderMark, warningTexts, foldedText } from './chunk-IZQLFUQU.js';
-import { validateExtendAtomsHostFree } from './chunk-R6JJZGXC.js';
-import { snapshotExtendMap, expandText } from './chunk-S7DZUVV3.js';
-import './chunk-NFS2REPQ.js';
-import './chunk-LIUB4EES.js';
+import { splitByteOrderMark } from './chunk-2TNTYI4L.js';
+import { orderWarningTexts, warningTexts, foldedText } from './chunk-KKUYU75D.js';
+import { validateExtendAtomsHostFree } from './chunk-63H2FLGU.js';
+import { snapshotExtendMap, expandText } from './chunk-MWHZ26S4.js';
+import './chunk-UVHGEVMV.js';
+import './chunk-SYNQJNVB.js';
+import './chunk-CUL5PLPI.js';
+import './chunk-2K5EBBF2.js';
+import './chunk-GZL2VW7C.js';
 import { readFileSync } from 'fs';
 
 function report(diagnostics, file, extend, onUnknown) {
@@ -19,6 +23,7 @@ function navePlugin(options = {}) {
   validateExtendAtomsHostFree(extend);
   const expandToText = (text, file) => {
     const result = expandText(text, { extend, onUnknown, from: file });
+    for (const line of orderWarningTexts(result.warnings, file)) console.warn(line);
     report(result.diagnostics, file, extend, onUnknown);
     return result;
   };

package/dist/postcss.d.ts

@@ -1,5 +1,22 @@
-import { Plugin } from 'postcss';
+import { Warning, Plugin } from 'postcss';
 import { AtomDefinition } from './atoms.js';
+import './atom-names-B8Ud-7zD.js';
+
+/**
+ * The one place the PostCSS host reports a warning: `node.warn()`, except under Next.js's
+ * Turbopack, which drops every PostCSS warning. There (detected by `process.env.TURBOPACK` being
+ * set) the text is printed with `console.warn` behind the same `file:line:column: ` frame the
+ * Lightning CSS adapter prints, and `node.warn()` is not called as well. A tool that runs the
+ * plugin itself and reports its warnings turns the printing off (`printWarnings: false`): every
+ * warning is then raised, whatever `TURBOPACK` says.
+ */
+
+/**
+ * Whether `warning` is an order warning (one `order-warnings.ts` or `shape-warnings.ts` makes)
+ * and not an `onUnknown` problem. No `onUnknown` governs it and it never fails a build, so a tool
+ * running the plugin with `printWarnings: false` reports it as a warning, never as a problem.
+ */
+declare function isOrderWarning(warning: Warning): boolean;
 
 /**
  * Nave PostCSS plugin — resolves @nave directives.
@@ -17,6 +34,7 @@ import { AtomDefinition } from './atoms.js';
  *   navePlugin()                         // Nave atoms only, fails build on unknown atom
  *   navePlugin({ extend: myAtoms })      // Nave + consumer atoms
  *   navePlugin({ onUnknown: 'warn' })    // Log and skip instead of failing the build
+ *   navePlugin({ onUnknown: 'warn', printWarnings: false }) // Raise warnings only, never print
  *
  * `extend` is trusted, consumer-authored code (your build config, or the module a path names),
  * which can already run arbitrary JavaScript at build time: it is not sanitised input. Every
@@ -76,10 +94,19 @@ interface NavePluginOptions {
      * 'ignore' — silently skip
      */
     onUnknown?: 'warn' | 'error' | 'ignore';
+    /**
+     * Whether a warning may be printed: a problem under 'warn', or an order warning. Under
+     * Turbopack (`TURBOPACK` set), which shows no PostCSS warning, the plugin prints each one with
+     * `console.warn` instead of raising it (default `true`). `false` raises it as a PostCSS warning
+     * only, whatever `TURBOPACK` says: for a tool that runs the plugin itself and reports the
+     * warnings it raises, telling the two apart with `isOrderWarning()`.
+     */
+    printWarnings?: boolean;
 }
 declare const navePlugin: {
     (options?: NavePluginOptions): Plugin;
     postcss: boolean;
 };
 
-export { AtomDefinition, type NavePluginOptions, navePlugin as default, navePlugin };
+export { AtomDefinition, navePlugin as default, isOrderWarning, navePlugin };
+export type { NavePluginOptions };