@navecss/core 0.2.0 → 0.4.0

package/dist/collect.d.ts

@@ -0,0 +1,279 @@
+export { R as ResolvedUsedOptions, U as UsedAtomOptions, a as assertOptions, k as keptAtoms, r as resolveUsedOptions } from './vite-options-D1-hGA9L.js';
+import './atom-names-2OreuBx9.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;
+
+/**
+ * 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 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.
+ */
+declare function buildReport(problems: readonly LocatedProblem[], configured: readonly string[], home: string): string;
+
+export { type AstNode, CX_SOURCE, type LocatedProblem, type ModuleReading, type Problem, type ProblemKind, REPORT_CAUSE, type ReadOptions, buildReport, readModule };

package/dist/collect.js

@@ -0,0 +1,4 @@
+export { CX_SOURCE, REPORT_CAUSE, assertOptions, buildReport, keptAtoms, readModule, resolveUsedOptions } from './chunk-E5F6YF7A.js';
+import './chunk-SYNQJNVB.js';
+import './chunk-CUL5PLPI.js';
+import './chunk-GZL2VW7C.js';

package/dist/cx.d.ts

@@ -1,4 +1,4 @@
-import { AtomName } from './atoms.js';
+import { A as AtomName } from './atom-names-2OreuBx9.js';
 
 /**
  * cx — typed atomic class composer for Nave.
@@ -9,10 +9,13 @@ import { AtomName } from './atoms.js';
  *                  unknown name is a compile error.
  *   cx.raw(...)  — any class string, returned untouched. The declared way to
  *                  step outside the system.
+ *   cx.dynamic(name) — one atom chosen at run time, for a name the Vite plugin's build
+ *                  cannot read (listed in the plugin's `keep` option).
  *
- * Both accept falsy arguments (undefined, null, false) and filter them out, so
- * conditional classes work the same on either side. Both return a
- * space-separated class string for className={}.
+ * cx() and cx.raw() accept falsy arguments (undefined, null, false) and filter
+ * them out, so conditional classes work the same on either side. Both return a
+ * space-separated class string for className={}. cx.dynamic() takes one atom
+ * name, or a falsy value, and returns that atom's class, or an empty string.
  *
  * Validation, not just autocomplete:
  *   cx() takes AtomName, so a typo'd name ('interactve'), a name typed from
@@ -40,6 +43,14 @@ import { AtomName } from './atoms.js';
  *   An atom name held in a variable needs a literal type. `const n = 'flex'`
  *   is one; a let binding, an array element or an object property widens to
  *   string, so annotate it with the exported AtomName type (or `as const`).
+ *   Under the Vite plugin the build reads the value as well as the type, and
+ *   only a value it can list builds. It can list a string literal, null,
+ *   undefined and false; a condition choosing between values it can list;
+ *   and a binding in the same file that is never assigned again (a const,
+ *   say) and is bound to a value it can list, another such binding included.
+ *   An array element or an object property fails the build whatever its
+ *   type. To choose by a value, call cx() once per case and pick between the
+ *   results: ({ row: cx('flex'), grid: cx('grid') })[variant].
  *
  * Why cx.raw() never maps:
  *   cx() resolves an atom name to that atom's global class, so cx('container')
@@ -67,6 +78,14 @@ type Falsy = false | null | undefined;
 interface Cx {
     (...args: (AtomName | Falsy)[]): string;
     raw: (...args: (Falsy | string)[]) => string;
+    /**
+     * One atom chosen at run time, for a name the build cannot read. Under the Vite plugin the
+     * name must be one the plugin ships: list every atom it can take in `keep` (or, for a package,
+     * in `keepFor`). Without the plugin it maps through every atom, like `cx()`, except that a
+     * name that is no atom returns `''` instead of passing through, so it never carries a class
+     * from outside Nave.
+     */
+    dynamic: (name: AtomName | Falsy) => string;
 }
 declare const cx: Cx;
 

package/dist/cx.js

@@ -1,9 +1,27 @@
-import { atomClassMap } from './chunk-BVON7XKC.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] : "";
+};
 
 export { cx };

package/dist/lightningcss.d.ts

@@ -0,0 +1,51 @@
+import { AtomDefinition } from './atoms.js';
+import './atom-names-2OreuBx9.js';
+
+interface NaveLightningOptions {
+    /**
+     * Consumer-defined atoms merged with Nave built-in atoms. Consumer atoms win on name collision.
+     * These atoms resolve via @nave only. No global class. Not available in cx().
+     *
+     * An object only: `expand` is synchronous, for `transform()`, so it cannot load a module.
+     * Import your atoms into the script that calls `navePlugin()`.
+     */
+    extend?: Record<string, AtomDefinition>;
+    /**
+     * Behaviour on a problem in a @nave directive: an unknown atom name, no atom named at all,
+     * anything but a name between the names (a comma, a string), a {} block, or a place the
+     * directive cannot expand. Under 'error', every such problem in one stylesheet is reported in
+     * one thrown error.
+     * 'warn'  — print each with `console.warn` and skip it
+     * 'error' — throw (default)
+     * 'ignore' — silently skip
+     */
+    onUnknown?: 'warn' | 'error' | 'ignore';
+}
+/**
+ * What `navePlugin()` returns: `expand` for `transform()`, and `resolver` for `bundleAsync()`.
+ */
+interface NaveLightningAdapter {
+    /**
+     * Expands the directives of `code` (the stylesheet's text, or its bytes) and returns the result
+     * as bytes with its source map, ready to pass to `transform()` as `code` and `inputSourceMap`.
+     * `filename` is what a message names.
+     */
+    expand(code: string | Uint8Array, filename: string): {
+        code: Uint8Array;
+        map: string;
+    };
+    /**
+     * For `bundleAsync()`: `read` reads a file and returns its expanded text. It returns no source
+     * map, and the inserted text adds no line breaks, so line numbers hold. A leading byte order
+     * mark is dropped, since the file is joined into a bundle, where one would sit mid-way.
+     */
+    resolver: {
+        read(filePath: string): string;
+    };
+}
+/**
+ * The Lightning CSS adapter: `expand` for `transform()` and `resolver` for `bundleAsync()`.
+ */
+declare function navePlugin(options?: NaveLightningOptions): NaveLightningAdapter;
+
+export { type NaveLightningAdapter, type NaveLightningOptions, navePlugin as default, navePlugin };

package/dist/lightningcss.js

@@ -0,0 +1,44 @@
+import { splitByteOrderMark, warningTexts, foldedText } from './chunk-2A7IUZBH.js';
+import { validateExtendAtomsHostFree } from './chunk-LQSGQ2OA.js';
+import { snapshotExtendMap, expandText } from './chunk-LADFXRWQ.js';
+import './chunk-NFS2REPQ.js';
+import './chunk-SYNQJNVB.js';
+import './chunk-CUL5PLPI.js';
+import './chunk-GZL2VW7C.js';
+import { readFileSync } from 'fs';
+
+function report(diagnostics, file, extend, onUnknown) {
+  if (onUnknown === "ignore" || diagnostics.length === 0) return;
+  if (onUnknown === "warn") {
+    for (const text of warningTexts(diagnostics, file, extend)) console.warn(text);
+    return;
+  }
+  throw new Error(foldedText(diagnostics, file, extend));
+}
+function navePlugin(options = {}) {
+  const onUnknown = options.onUnknown ?? "error";
+  const extend = snapshotExtendMap(options.extend ?? {});
+  validateExtendAtomsHostFree(extend);
+  const expandToText = (text, file) => {
+    const result = expandText(text, { extend, onUnknown, from: file });
+    report(result.diagnostics, file, extend, onUnknown);
+    return result;
+  };
+  return {
+    expand(code, filename) {
+      const raw = typeof code === "string" ? code : new TextDecoder("utf-8", { ignoreBOM: true }).decode(code);
+      const { bom, text } = splitByteOrderMark(raw);
+      const { css, map } = expandToText(text, filename);
+      return { code: new TextEncoder().encode(bom + css), map };
+    },
+    resolver: {
+      read: (filePath) => {
+        const { text } = splitByteOrderMark(readFileSync(filePath, "utf8"));
+        return expandToText(text, filePath).css;
+      }
+    }
+  };
+}
+var lightningcss_default = navePlugin;
+
+export { lightningcss_default as default, navePlugin };

package/dist/no-tokens.css

@@ -12,13 +12,13 @@
  * WHAT YOU MUST SUPPLY. This entry ships Nave's reset and atomic layers and
  * imports no token values at all, so every '--nave-' custom property those
  * two layers read has to come from your own stylesheet, not only the colours.
- * A property you do not define is not an error: the declaration that reads it is
- * discarded, and the property does NOT fall back to whatever Nave's earlier rules
- * set for it, so the element silently loses that piece of styling.
- * To pick one that matters, the focus outline on '.nave-focus-ring' is built
- * from '--nave-border-width-focus', so a token layer that defines every colour
- * and not that width leaves an element carrying that class with no visible
- * outline when it is focused.
+ * A property you do not define is not an error: a declaration that reads it with
+ * no fallback is discarded, and the property does NOT fall back to whatever Nave's
+ * earlier rules set for it, so the element silently loses that piece of styling.
+ * To pick one, '.nave-border' is a single 'border' shorthand built from
+ * '--nave-border-width-sm' and '--nave-color-border-default', so a token layer
+ * that defines every width and not that colour leaves an element carrying that
+ * class with no border from it at all, not a border in some other colour.
  *
  * Nave ships a contract manifest listing the custom properties it requires
  * ('@navecss/tokens/core-contract'). The manifest is generated by scanning

package/dist/postcss.cjs

@@ -0,0 +1 @@
+module.exports = require('./postcss.js').navePlugin

package/dist/postcss.d.cts

@@ -0,0 +1,2 @@
+import { navePlugin } from './postcss.js'
+export = navePlugin

package/dist/postcss.d.ts

@@ -1,14 +1,17 @@
 import { Plugin } from 'postcss';
 import { AtomDefinition } from './atoms.js';
+import './atom-names-2OreuBx9.js';
 
 /**
  * Nave PostCSS plugin — resolves @nave directives.
  *
- * Inlines atomic utility declarations at build time.
- * Pseudo rules, @media and @container blocks are emitted as native CSS
- * nesting inside the parent rule (`&:focus-visible { … }`), never hoisted
- * out as sibling rules. Browser floor: Baseline 2024.
- * See https://github.com/navecss/navecss/blob/main/docs/04-adr/0001-native-css-nesting.md
+ * A thin adapter over the host-free directive core (`src/directive/`):
+ * `plan()` decides what a directive expands to and where it goes, this
+ * file only wires the PostCSS plugin lifecycle to `handleAtRule()`
+ * (`postcss-at-rule.ts`), which walks the AST to answer `plan()`'s three
+ * facts and splices its result back in as PostCSS nodes. Setup, options and
+ * observable behaviour are unchanged except where this package's CHANGELOG
+ * says so.
  *
  * Setup:
  *   import { navePlugin } from '@navecss/core/postcss'
@@ -16,12 +19,12 @@ import { AtomDefinition } from './atoms.js';
  *   navePlugin({ extend: myAtoms })      // Nave + consumer atoms
  *   navePlugin({ onUnknown: 'warn' })    // Log and skip instead of failing the build
  *
- * `extend` is trusted, consumer-authored code, run at build time in the same file that could
- * already run arbitrary JavaScript — it is not sanitised input. `validateExtendAtoms` still
- * parses every declaration, pseudo selector key, and media/container condition an atom carries,
- * and rejects any that does not parse as exactly that one construct, since a typo there is
- * otherwise silent CSS injection into the generated output rather than a build error at the
- * point of the mistake.
+ * `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
+ * declaration, pseudo selector key, and media/container condition an atom carries is still
+ * parsed, and one that does not parse as exactly that one construct is refused, since a typo
+ * there is otherwise silent CSS injection into the generated output rather than a build error
+ * at the point of the mistake.
  *
  * Consumer atoms:
  *   import type { AtomDefinition } from '@navecss/core/postcss'
@@ -52,11 +55,23 @@ interface NavePluginOptions {
      * Consumer-defined atoms merged with Nave built-in atoms.
      * Consumer atoms win on name collision — your system owns its vocabulary.
      * These atoms resolve via @nave only. No global class. Not available in cx().
+     *
+     * A string is a path to a module instead, resolved against `process.cwd()`
+     * at construction (a path that names no file throws right there, naming
+     * the path and the directory; a package name is not looked up), then
+     * loaded for its default export on every run and re-read whenever the
+     * file's own bytes change (the modules it imports are not). Pass a
+     * path when your host's build cache needs to see it as a dependency: an
+     * inline object is invisible to a cached host's own cache key. A path
+     * makes the plugin async: use `process(css).then(cb)`, not the sync `.css`
+     * getter.
      */
-    extend?: Record<string, AtomDefinition>;
+    extend?: Record<string, AtomDefinition> | string;
     /**
-     * Behaviour on an unknown atom name, or a @nave directive that names no
-     * atom at all.
+     * Behaviour on a problem in a @nave directive: an unknown atom name, no
+     * atom named at all, anything but a name between the names (a comma, a
+     * string), a {} block, or a place the directive cannot expand. Under
+     * 'error', every such problem in one stylesheet is reported in one error.
      * 'warn'  — log and skip
      * 'error' — throw, failing the build (default)
      * 'ignore' — silently skip
@@ -68,4 +83,4 @@ declare const navePlugin: {
     postcss: boolean;
 };
 
-export { AtomDefinition, type NavePluginOptions, navePlugin };
+export { AtomDefinition, type NavePluginOptions, navePlugin as default, navePlugin };