@navecss/core 0.1.1 → 0.3.0

package/dist/chunk-UANF3FGO.js

@@ -0,0 +1,115 @@
+import { createPositionFinder, tokenize, matchBrackets, readItem, isNaveAtKeyword } from './chunk-NFS2REPQ.js';
+
+// src/directive/find-survivors.ts
+var NATURAL_STOP_CHARS = /* @__PURE__ */ new Set(["\n", ";", "}"]);
+function naturalTextAfter(css, offset) {
+  let end = css.length;
+  for (let i = offset; i < css.length; i++) {
+    if (NATURAL_STOP_CHARS.has(css[i])) {
+      end = i;
+      break;
+    }
+  }
+  return css.slice(offset, end).trim();
+}
+function isStructural(token) {
+  return token.type !== "whitespace-token" && token.type !== "comment";
+}
+function skipInert(tokens, i, limit) {
+  let j = i;
+  while (j < limit && !isStructural(tokens[j])) j++;
+  return j;
+}
+var Scan = class {
+  closerFor;
+  css;
+  survivors = [];
+  tokens;
+  constructor(css) {
+    this.css = css;
+    this.tokens = tokenize(css);
+    this.closerFor = matchBrackets(this.tokens);
+  }
+};
+function scanForNaveTokens(scan, start, end, selector) {
+  for (let i = start; i < end; i++) {
+    const token = scan.tokens[i];
+    if (isNaveAtKeyword(token))
+      scan.survivors.push({
+        offset: token.startIndex,
+        text: naturalTextAfter(scan.css, token.startIndex),
+        selector
+      });
+  }
+}
+function ruleSelector(scan, item) {
+  const braceIndex = item.blockStart - 1;
+  return scan.css.slice(scan.tokens[item.start].startIndex, scan.tokens[braceIndex].startIndex).trim();
+}
+function childFrameFor(scan, item, selector) {
+  if (item.blockStart === void 0 || item.blockEnd === void 0) return void 0;
+  const childSelector = item.kind === "rule" ? ruleSelector(scan, item) : selector;
+  return {
+    i: skipInert(scan.tokens, item.blockStart, item.blockEnd),
+    limit: item.blockEnd,
+    selector: childSelector
+  };
+}
+function preludeEnd(item) {
+  return item.blockStart === void 0 ? item.end : item.blockStart - 1;
+}
+function visitItem(scan, item, selector) {
+  switch (item.kind) {
+    case "at-rule":
+    case "rule": {
+      scanForNaveTokens(scan, item.start, preludeEnd(item), selector);
+      return childFrameFor(scan, item, selector);
+    }
+    case "declaration":
+    case "invalid": {
+      scanForNaveTokens(scan, item.start, item.end, selector);
+      return void 0;
+    }
+  }
+}
+function walkBlock(scan, start, limit, selector) {
+  const stack = [{ i: skipInert(scan.tokens, start, limit), limit, selector }];
+  while (stack.length > 0) {
+    const frame = stack.at(-1);
+    if (frame.i >= frame.limit) {
+      stack.pop();
+      continue;
+    }
+    const item = readItem(scan.tokens, frame.i, frame.limit, scan.closerFor);
+    frame.i = skipInert(scan.tokens, item.end, frame.limit);
+    const child = visitItem(scan, item, frame.selector);
+    if (child) stack.push(child);
+  }
+}
+function findSurvivors(css) {
+  const scan = new Scan(css);
+  walkBlock(scan, 0, scan.tokens.length, void 0);
+  return scan.survivors;
+}
+
+// src/directive/findings.ts
+function findingsInText(file, raw) {
+  const css = raw.startsWith("\uFEFF") ? raw.slice(1) : raw;
+  const positionAt = createPositionFinder(css);
+  return findSurvivors(css).map((survivor) => {
+    const position = positionAt(survivor.offset);
+    return {
+      file,
+      line: position.line,
+      column: position.column + 1,
+      text: survivor.text,
+      ...survivor.selector !== void 0 && { selector: survivor.selector }
+    };
+  });
+}
+function formatFinding(finding) {
+  const where = finding.selector === void 0 ? "" : ` (in ${finding.selector.replaceAll(/\s+/g, " ")})`;
+  return `${finding.file}:${finding.line}:${finding.column}: ${finding.text}${where}`;
+}
+
+export { findingsInText, formatFinding };

package/dist/chunk-XQQCDUV6.js

@@ -0,0 +1,152 @@
+import { findingsInText } from './chunk-UANF3FGO.js';
+import { readFile, stat, realpath, readdir } from 'fs/promises';
+import path from 'path';
+
+var NotAStylesheetPathError = class extends Error {
+  path;
+  constructor(path2) {
+    super(`${path2} is not a stylesheet file`);
+    this.path = path2;
+    this.name = "NotAStylesheetPathError";
+  }
+};
+function hasCssExtension(name) {
+  return path.extname(name).toLowerCase() === ".css";
+}
+async function entryKind(entry, entryPath, state) {
+  if (entry.isDirectory()) return "directory";
+  if (entry.isFile()) return hasCssExtension(entry.name) ? "css-file" : "skip";
+  if (!entry.isSymbolicLink()) return "skip";
+  let targetStats;
+  try {
+    targetStats = await stat(entryPath);
+  } catch {
+    if (hasCssExtension(entry.name)) state.unreadablePaths.push(entryPath);
+    return "skip";
+  }
+  if (targetStats.isDirectory()) return "directory";
+  if (targetStats.isFile()) return hasCssExtension(entry.name) ? "css-file" : "skip";
+  return "skip";
+}
+async function listSubdirectory(entryPath, state) {
+  let canonicalPath;
+  try {
+    canonicalPath = await realpath(entryPath);
+  } catch {
+    state.unreadablePaths.push(entryPath);
+    return [];
+  }
+  if (state.visitedDirs.has(canonicalPath)) return [];
+  state.visitedDirs.add(canonicalPath);
+  return listDirectory(entryPath, state);
+}
+async function cssFileIfNew(entryPath, state) {
+  let canonicalFile;
+  try {
+    canonicalFile = await realpath(entryPath);
+  } catch {
+    state.unreadablePaths.push(entryPath);
+    return void 0;
+  }
+  if (state.reportedRealFiles.has(canonicalFile)) return void 0;
+  state.reportedRealFiles.add(canonicalFile);
+  return entryPath;
+}
+async function listDirectory(dir, state) {
+  let entries;
+  try {
+    entries = await readdir(dir, { withFileTypes: true });
+  } catch {
+    state.unreadablePaths.push(dir);
+    return [];
+  }
+  const files = [];
+  for (const entry of entries) {
+    const entryPath = path.join(dir, entry.name);
+    const kind = await entryKind(entry, entryPath, state);
+    if (kind === "directory") {
+      files.push(...await listSubdirectory(entryPath, state));
+    } else if (kind === "css-file") {
+      const file = await cssFileIfNew(entryPath, state);
+      if (file) files.push(file);
+    }
+  }
+  return files;
+}
+async function listCssFiles(source) {
+  const stats = await stat(source);
+  if (!stats.isDirectory()) {
+    if (!stats.isFile()) throw new NotAStylesheetPathError(source);
+    return { files: [source], unreadablePaths: [] };
+  }
+  const canonicalRoot = await realpath(source);
+  const state = {
+    reportedRealFiles: /* @__PURE__ */ new Set(),
+    unreadablePaths: [],
+    visitedDirs: /* @__PURE__ */ new Set([canonicalRoot])
+  };
+  const files = await listDirectory(source, state);
+  return { files, unreadablePaths: state.unreadablePaths };
+}
+
+// src/directive/check-run.ts
+async function wasFileRead(file, findings) {
+  let raw;
+  try {
+    raw = await readFile(file, "utf8");
+  } catch {
+    return false;
+  }
+  for (const finding of findingsInText(file, raw)) findings.push(finding);
+  return true;
+}
+async function sourceOutcome(source) {
+  try {
+    return { kind: "listing", listing: await listCssFiles(source) };
+  } catch (error) {
+    if (error instanceof NotAStylesheetPathError) return { kind: "not-a-stylesheet" };
+    return { kind: "unreadable" };
+  }
+}
+function statusFor(hasUnreadableSource, stylesheetsRead, findingCount) {
+  if (hasUnreadableSource || stylesheetsRead === 0) return 2;
+  return findingCount > 0 ? 1 : 0;
+}
+async function runCheck(source) {
+  const findings = [];
+  const unreadablePaths = [];
+  const notStylesheetPaths = [];
+  let stylesheetsRead = 0;
+  let hasUnreadableSource = false;
+  for (const one of source) {
+    const outcome = await sourceOutcome(one);
+    if (outcome.kind === "unreadable") {
+      hasUnreadableSource = true;
+      unreadablePaths.push(one);
+      continue;
+    }
+    if (outcome.kind === "not-a-stylesheet") {
+      hasUnreadableSource = true;
+      notStylesheetPaths.push(one);
+      continue;
+    }
+    const listing = outcome.listing;
+    if (listing.unreadablePaths.length > 0) {
+      hasUnreadableSource = true;
+      unreadablePaths.push(...listing.unreadablePaths);
+    }
+    for (const file of listing.files) {
+      const wasReadable = await wasFileRead(file, findings);
+      if (wasReadable) {
+        stylesheetsRead++;
+      } else {
+        hasUnreadableSource = true;
+        unreadablePaths.push(file);
+      }
+    }
+  }
+  const status = statusFor(hasUnreadableSource, stylesheetsRead, findings.length);
+  return { result: { status, findings, stylesheetsRead }, unreadablePaths, notStylesheetPaths };
+}
+
+export { runCheck };

package/dist/cx.d.ts

@@ -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')
@@ -51,10 +62,11 @@ import { AtomName } from './atoms.js';
  *   relative, absolute, gap, truncate, interactive.
  *
  * What is NOT checked:
- *   Nothing here looks at the rest of the className attribute. A bare string
- *   sitting beside these calls is not seen by anything, so cx.raw() is a
- *   DECLARED escape channel (greppable: `grep -r 'cx.raw'`), not an enforced
- *   one.
+ *   Nothing here looks at the rest of the className attribute. @navecss/eslint-plugin does:
+ *   install it for an ENFORCED escape channel, reporting an undeclared literal class written
+ *   in className and requiring a reason on a cx.raw() call that carries one (a class the
+ *   project declares as its own passes by design). Without it, cx.raw() is only a DECLARED
+ *   escape channel (greppable: `grep -r 'cx.raw'`).
  *
  * Note on consumer atoms:
  *   Atoms defined via navePlugin({ extend }) are @nave-directive only.
@@ -66,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,14 @@
-import { atomClassMap } from './chunk-BVON7XKC.js';
+import { atomClassMap } from './chunk-LIUB4EES.js';
 
 // src/cx.ts
 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 "";
+  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,50 @@
+import { AtomDefinition } from './atoms.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,42 @@
+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 { 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

@@ -4,11 +4,13 @@ import { AtomDefinition } from './atoms.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,6 +18,13 @@ 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 (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'
  *   import { media } from '@navecss/tokens/breakpoints'
@@ -45,11 +54,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
@@ -61,4 +82,4 @@ declare const navePlugin: {
     postcss: boolean;
 };
 
-export { AtomDefinition, type NavePluginOptions, navePlugin };
+export { AtomDefinition, type NavePluginOptions, navePlugin as default, navePlugin };