@kbach/react 1.0.0-beta.0 → 1.0.0-beta.10

package/dist/postcss-plugin.mjs

@@ -0,0 +1,79 @@
+import {
+  DEFAULT_SCAN_DIRS,
+  createKbachStaticCssEngine,
+  resolveEffectiveTheme
+} from "./chunk-J2M6QWJW.mjs";
+import "./chunk-4Y2QXNJY.mjs";
+import "./chunk-EOSN5CYG.mjs";
+
+// src/postcss-plugin/index.ts
+import postcss from "postcss";
+import { resolve as resolvePath } from "path";
+var KBACH_START_TEXT = "kbach:start";
+var KBACH_END_TEXT = "kbach:end";
+function isKbachMarker(node, text) {
+  return !!node && node.type === "comment" && node.text === text;
+}
+function spliceGeneratedCss(root, generatedCss) {
+  const nodes = root.nodes;
+  let startIdx = -1;
+  let endIdx = -1;
+  for (let i = 0; i < nodes.length; i++) {
+    if (startIdx === -1 && isKbachMarker(nodes[i], KBACH_START_TEXT)) {
+      startIdx = i;
+      continue;
+    }
+    if (startIdx !== -1 && isKbachMarker(nodes[i], KBACH_END_TEXT)) {
+      endIdx = i;
+      break;
+    }
+  }
+  if (startIdx === -1 || endIdx === -1) {
+    console.warn(
+      `[kbach] postcss plugin: no "/* kbach:start */" / "/* kbach:end */" marker pair found \u2014 add both to the file this plugin processes (see @kbach/react/vite's own convention). Nothing was generated.`
+    );
+    return;
+  }
+  for (const stale of nodes.slice(startIdx + 1, endIdx)) stale.remove();
+  const parsed = postcss.parse(generatedCss);
+  const newNodes = [...parsed.nodes];
+  let after = nodes[startIdx];
+  for (const node of newNodes) {
+    root.insertAfter(after, node);
+    after = node;
+  }
+}
+function kbachPostcss(options = {}) {
+  return {
+    postcssPlugin: "kbach",
+    async Once(root, { result }) {
+      const projectRoot = options.root ?? process.cwd();
+      const theme = await resolveEffectiveTheme(projectRoot, options);
+      const includeDirs = options.include ?? DEFAULT_SCAN_DIRS;
+      const safelist = options.safelist ?? [];
+      const engine = createKbachStaticCssEngine({
+        root: projectRoot,
+        theme,
+        themeJson: JSON.stringify(theme),
+        includeDirs,
+        safelist
+      });
+      engine.scanProjectCssSelectorsOnce();
+      engine.initialScan();
+      engine.processSafelist();
+      for (const dir of includeDirs) {
+        result.messages.push({
+          type: "dir-dependency",
+          plugin: "kbach",
+          dir: resolvePath(projectRoot, dir),
+          glob: "**/*"
+        });
+      }
+      spliceGeneratedCss(root, engine.generateCSS());
+    }
+  };
+}
+kbachPostcss.postcss = true;
+export {
+  kbachPostcss as default
+};

package/dist/vite-plugin.d.mts

@@ -1,9 +1,23 @@
 import { Plugin } from 'vite';
-import { T as ThemeConfig } from './theme-BKAb78KP.mjs';
+import { T as ThemeConfig, K as KbachConfig } from './config-BQ_b-qxF.mjs';
 
 interface KbachPluginOptions {
     /** Defaults to the same defaultTheme the runtime uses — pass your own to keep both in sync. */
     theme?: ThemeConfig;
+    /**
+     * A `kbach.config.js`-style config object, resolved the same way
+     * `applyKbachConfig()` resolves it for the runtime — import the SAME
+     * config file here and in your app's own `applyKbachConfig()` call, and
+     * build-time CSS generation and runtime resolution always agree, with no
+     * synchronization step needed (`resolveKbachConfig` is a pure function:
+     * same input, same output, in Node.js here and in the browser there).
+     * Ignored if `theme` is also supplied. Only needed for an explicit
+     * override, though — if BOTH this and `theme` are omitted, `kbach()`
+     * auto-discovers a `kbach.config.js` at the project root on its own (see
+     * `loadConfigFile`'s own doc comment), the same zero-config convenience
+     * `tailwind.config.js` gets from Tailwind's own PostCSS plugin.
+     */
+    config?: KbachConfig;
     /** Directories to scan for class strings (relative to Vite root). */
     include?: string[];
     /**
@@ -13,16 +27,104 @@ interface KbachPluginOptions {
      * purpose as Tailwind's `safelist`.
      */
     safelist?: string[];
+    /**
+     * Path to the `kbach:start`/`kbach:end` marker file, relative to Vite's
+     * resolved root. Not needed for the common case — `kbach()` auto-detects
+     * it (see `findMainCSSFile`'s own doc comment) by finding wherever you
+     * actually put the two marker comments, regardless of whether your
+     * project's source root is `src/`, `app/` (React Router v7's framework
+     * mode), or anything else in `include`. Set this explicitly only to
+     * disambiguate a genuinely unusual layout (a marker file outside every
+     * `include` directory, or more than one candidate present at once).
+     */
+    cssFile?: string;
 }
+/**
+ * Finds where to read/write the `kbach:start`/`kbach:end` marker file,
+ * with no configuration required for the common case:
+ *
+ * 1. An explicit `cssFile` always wins (the one supported escape hatch).
+ * 2. Otherwise, look for a `kbach.css` already containing BOTH markers in
+ *    each `include` directory (in order) and the project root itself —
+ *    wherever you actually created it is where this plugin keeps using it,
+ *    regardless of which framework convention (`src/`, `app/`, ...) that
+ *    is. This is what makes React Router v7's framework mode (`app/
+ *    kbach.css`) and a plain Vite app (`src/kbach.css`) both "just work"
+ *    with the exact same `kbach()` call — no per-framework option needed.
+ * 3. No marked file exists yet (first run in a fresh project) — pick the
+ *    first `include` directory that already exists as a real directory on
+ *    disk, so the file this plugin is about to CREATE lands somewhere that
+ *    won't need its own parent directory made up out of nothing.
+ * 4. Nothing in `include` exists yet either (a genuinely empty project,
+ *    scaffolded before its first source file) — fall back to the first
+ *    configured `include` entry regardless; `writeMainCSSFile` (below)
+ *    creates its parent directory unconditionally, so this never crashes
+ *    even here.
+ */
+declare function findMainCSSFile(root: string, includeDirs: string[], explicitCssFile?: string): string;
+declare const DEFAULT_SCAN_DIRS: string[];
+declare const CSS_SYNC_DEBOUNCE_MS = 50;
+/**
+ * Auto-discovers a `kbach.config.*` file at the project root — `undefined`
+ * if none exists (the common case: most projects have no customization at
+ * all, so this is a silent, expected no-op, not a warning).
+ *
+ * Checks three filenames, in order, mirroring Node's own module-format
+ * conventions rather than assuming one: `kbach.config.cjs` (always
+ * CommonJS, `module.exports = {...}` — the one unambiguous choice
+ * regardless of the project's package.json) and `kbach.config.mjs`
+ * (always real ESM, `export default {...}`) are tried first, each loaded
+ * the one way that's guaranteed correct for that extension. Only the bare
+ * `kbach.config.js` — whose actual meaning depends on the nearest
+ * package.json's `"type"` field, exactly like every other `.js` file in
+ * the project — needs the fallback below: try `require()` first (correct
+ * for `"type": "commonjs"`/no `"type"` field, the more common case), and
+ * only on a failure that specifically indicates an ESM/CJS mismatch (see
+ * `isEsmRequireFailure`), retry via a real dynamic `import()` instead. A
+ * genuine syntax error in an otherwise-correctly-formatted config file is
+ * NOT caught here — it propagates as a real, actionable build failure,
+ * rather than being silently swallowed into a confusing second attempt.
+ *
+ * `require()` is built via `createRequire(root)` rather than
+ * `createRequire(import.meta.url)` — this file is written as ESM source,
+ * but tsup's CJS build output has no real `import.meta.url` (esbuild
+ * leaves it `undefined` there), which would make `createRequire` throw for
+ * anyone consuming this package's `require('@kbach/react/vite')` entry.
+ * `root` works as `createRequire`'s base in either build: it's always an
+ * absolute, already-`existsSync`-validated directory, and `require()`
+ * given an already-absolute `path` doesn't consult the base for
+ * resolution anyway — the base only matters for a relative specifier,
+ * which this never passes it. `import()` needs a real `file://` URL, not
+ * a bare Windows path (`C:\...` isn't a valid ESM specifier) — hence
+ * `pathToFileURL`.
+ */
+declare function loadConfigFile(root: string): Promise<KbachConfig | undefined>;
+/**
+ * Resolves the theme to use, applying the same "explicit theme/config
+ * always wins over kbach.config.js auto-discovery" precedence both
+ * vite-plugin and postcss-plugin need identically.
+ */
+declare function resolveEffectiveTheme(root: string, options: {
+    theme?: ThemeConfig;
+    config?: KbachConfig;
+}): Promise<ThemeConfig>;
 /**
  * Build-time static CSS generation for Vite — scans source files for
  * Kbach class strings, resolves them through the same Rust engine the
  * runtime uses (via the Node-target WASM build, see wasmNode.ts), and
- * writes a real kbach.css. Simplified vs old-kbach's version: expects
- * `src/kbach.css` to exist at a fixed conventional path (create it with
- * `/* kbach:start *\/` / `/* kbach:end *\/` markers) rather than scanning
- * the whole project for a file named kbach.css.
+ * writes a real kbach.css. Auto-detects WHERE that file is (or should be
+ * created) via `findMainCSSFile` — no per-framework config needed for
+ * `src/`, `app/` (React Router v7's framework mode), or any other
+ * `include` convention; create a file with `/* kbach:start *\/` / `/*
+ * kbach:end *\/` markers wherever your project's source actually lives
+ * and this plugin finds it there.
+ *
+ * The actual scanning/resolution/generation logic lives in
+ * `staticCss/engine.ts`, shared with `postcss-plugin/index.ts` (Next.js/
+ * webpack/Turbopack) — this file is now just the Vite-specific wiring:
+ * plugin lifecycle hooks, the dev-server watcher, and the debounced
+ * file-write.
  */
 declare function kbach(options?: KbachPluginOptions): Plugin;
 
-export { type KbachPluginOptions, kbach };
+export { CSS_SYNC_DEBOUNCE_MS, DEFAULT_SCAN_DIRS, type KbachPluginOptions, findMainCSSFile, kbach, loadConfigFile, resolveEffectiveTheme };

package/dist/vite-plugin.d.ts

@@ -1,9 +1,23 @@
 import { Plugin } from 'vite';
-import { T as ThemeConfig } from './theme-BKAb78KP.js';
+import { T as ThemeConfig, K as KbachConfig } from './config-BQ_b-qxF.js';
 
 interface KbachPluginOptions {
     /** Defaults to the same defaultTheme the runtime uses — pass your own to keep both in sync. */
     theme?: ThemeConfig;
+    /**
+     * A `kbach.config.js`-style config object, resolved the same way
+     * `applyKbachConfig()` resolves it for the runtime — import the SAME
+     * config file here and in your app's own `applyKbachConfig()` call, and
+     * build-time CSS generation and runtime resolution always agree, with no
+     * synchronization step needed (`resolveKbachConfig` is a pure function:
+     * same input, same output, in Node.js here and in the browser there).
+     * Ignored if `theme` is also supplied. Only needed for an explicit
+     * override, though — if BOTH this and `theme` are omitted, `kbach()`
+     * auto-discovers a `kbach.config.js` at the project root on its own (see
+     * `loadConfigFile`'s own doc comment), the same zero-config convenience
+     * `tailwind.config.js` gets from Tailwind's own PostCSS plugin.
+     */
+    config?: KbachConfig;
     /** Directories to scan for class strings (relative to Vite root). */
     include?: string[];
     /**
@@ -13,16 +27,104 @@ interface KbachPluginOptions {
      * purpose as Tailwind's `safelist`.
      */
     safelist?: string[];
+    /**
+     * Path to the `kbach:start`/`kbach:end` marker file, relative to Vite's
+     * resolved root. Not needed for the common case — `kbach()` auto-detects
+     * it (see `findMainCSSFile`'s own doc comment) by finding wherever you
+     * actually put the two marker comments, regardless of whether your
+     * project's source root is `src/`, `app/` (React Router v7's framework
+     * mode), or anything else in `include`. Set this explicitly only to
+     * disambiguate a genuinely unusual layout (a marker file outside every
+     * `include` directory, or more than one candidate present at once).
+     */
+    cssFile?: string;
 }
+/**
+ * Finds where to read/write the `kbach:start`/`kbach:end` marker file,
+ * with no configuration required for the common case:
+ *
+ * 1. An explicit `cssFile` always wins (the one supported escape hatch).
+ * 2. Otherwise, look for a `kbach.css` already containing BOTH markers in
+ *    each `include` directory (in order) and the project root itself —
+ *    wherever you actually created it is where this plugin keeps using it,
+ *    regardless of which framework convention (`src/`, `app/`, ...) that
+ *    is. This is what makes React Router v7's framework mode (`app/
+ *    kbach.css`) and a plain Vite app (`src/kbach.css`) both "just work"
+ *    with the exact same `kbach()` call — no per-framework option needed.
+ * 3. No marked file exists yet (first run in a fresh project) — pick the
+ *    first `include` directory that already exists as a real directory on
+ *    disk, so the file this plugin is about to CREATE lands somewhere that
+ *    won't need its own parent directory made up out of nothing.
+ * 4. Nothing in `include` exists yet either (a genuinely empty project,
+ *    scaffolded before its first source file) — fall back to the first
+ *    configured `include` entry regardless; `writeMainCSSFile` (below)
+ *    creates its parent directory unconditionally, so this never crashes
+ *    even here.
+ */
+declare function findMainCSSFile(root: string, includeDirs: string[], explicitCssFile?: string): string;
+declare const DEFAULT_SCAN_DIRS: string[];
+declare const CSS_SYNC_DEBOUNCE_MS = 50;
+/**
+ * Auto-discovers a `kbach.config.*` file at the project root — `undefined`
+ * if none exists (the common case: most projects have no customization at
+ * all, so this is a silent, expected no-op, not a warning).
+ *
+ * Checks three filenames, in order, mirroring Node's own module-format
+ * conventions rather than assuming one: `kbach.config.cjs` (always
+ * CommonJS, `module.exports = {...}` — the one unambiguous choice
+ * regardless of the project's package.json) and `kbach.config.mjs`
+ * (always real ESM, `export default {...}`) are tried first, each loaded
+ * the one way that's guaranteed correct for that extension. Only the bare
+ * `kbach.config.js` — whose actual meaning depends on the nearest
+ * package.json's `"type"` field, exactly like every other `.js` file in
+ * the project — needs the fallback below: try `require()` first (correct
+ * for `"type": "commonjs"`/no `"type"` field, the more common case), and
+ * only on a failure that specifically indicates an ESM/CJS mismatch (see
+ * `isEsmRequireFailure`), retry via a real dynamic `import()` instead. A
+ * genuine syntax error in an otherwise-correctly-formatted config file is
+ * NOT caught here — it propagates as a real, actionable build failure,
+ * rather than being silently swallowed into a confusing second attempt.
+ *
+ * `require()` is built via `createRequire(root)` rather than
+ * `createRequire(import.meta.url)` — this file is written as ESM source,
+ * but tsup's CJS build output has no real `import.meta.url` (esbuild
+ * leaves it `undefined` there), which would make `createRequire` throw for
+ * anyone consuming this package's `require('@kbach/react/vite')` entry.
+ * `root` works as `createRequire`'s base in either build: it's always an
+ * absolute, already-`existsSync`-validated directory, and `require()`
+ * given an already-absolute `path` doesn't consult the base for
+ * resolution anyway — the base only matters for a relative specifier,
+ * which this never passes it. `import()` needs a real `file://` URL, not
+ * a bare Windows path (`C:\...` isn't a valid ESM specifier) — hence
+ * `pathToFileURL`.
+ */
+declare function loadConfigFile(root: string): Promise<KbachConfig | undefined>;
+/**
+ * Resolves the theme to use, applying the same "explicit theme/config
+ * always wins over kbach.config.js auto-discovery" precedence both
+ * vite-plugin and postcss-plugin need identically.
+ */
+declare function resolveEffectiveTheme(root: string, options: {
+    theme?: ThemeConfig;
+    config?: KbachConfig;
+}): Promise<ThemeConfig>;
 /**
  * Build-time static CSS generation for Vite — scans source files for
  * Kbach class strings, resolves them through the same Rust engine the
  * runtime uses (via the Node-target WASM build, see wasmNode.ts), and
- * writes a real kbach.css. Simplified vs old-kbach's version: expects
- * `src/kbach.css` to exist at a fixed conventional path (create it with
- * `/* kbach:start *\/` / `/* kbach:end *\/` markers) rather than scanning
- * the whole project for a file named kbach.css.
+ * writes a real kbach.css. Auto-detects WHERE that file is (or should be
+ * created) via `findMainCSSFile` — no per-framework config needed for
+ * `src/`, `app/` (React Router v7's framework mode), or any other
+ * `include` convention; create a file with `/* kbach:start *\/` / `/*
+ * kbach:end *\/` markers wherever your project's source actually lives
+ * and this plugin finds it there.
+ *
+ * The actual scanning/resolution/generation logic lives in
+ * `staticCss/engine.ts`, shared with `postcss-plugin/index.ts` (Next.js/
+ * webpack/Turbopack) — this file is now just the Vite-specific wiring:
+ * plugin lifecycle hooks, the dev-server watcher, and the debounced
+ * file-write.
  */
 declare function kbach(options?: KbachPluginOptions): Plugin;
 
-export { type KbachPluginOptions, kbach };
+export { CSS_SYNC_DEBOUNCE_MS, DEFAULT_SCAN_DIRS, type KbachPluginOptions, findMainCSSFile, kbach, loadConfigFile, resolveEffectiveTheme };