@kbach/ui 0.1.0-beta.6 → 0.1.0-beta.7

package/KBACH.md

@@ -122,12 +122,19 @@ const Button = styled('button', 'bg-blue-7 hover:bg-blue-8 rounded-xl px-6 py-3'
 On web, `styled()` forwards the full class string as `className` so CSS rules (group-hover:, before:, print:) match the element.
 
 ### useStyles(classes)
-Resolve classes to a style object inside a component.
+Resolve classes to a style object inside a component. This is also the escape hatch for genuinely dynamic class strings (`` `bg-${color}-${shade}` ``) that the static Vite plugin can't discover by scanning source text — it always resolves at render time regardless.
 ```jsx
 import { useStyles } from '@kbach/ui';
 const style = useStyles('bg-blue-6 px-3 py-1 rounded-full');
 return <span style={style}>Badge</span>;
 ```
+Want that same dynamic set of classes as real CSS in the static file instead of an inline style? Generate the full list yourself and pass it to the plugin's `safelist` option:
+```ts
+// vite.config.ts
+const families = ['red', 'blue' /* … */];
+const shades = [1, 2, 3 /* … */];
+kbach({ safelist: families.flatMap((f) => shades.map((s) => `bg-${f}-${s}`)) })
+```
 
 ### kb(classes)
 Resolve outside a component (static contexts).

package/dist/vite-plugin.d.mts

@@ -150,6 +150,24 @@ interface KbachPluginOptions {
     framework?: FrameworkConfig;
     /** Directories to scan for class strings (relative to Vite root). Defaults to common source dirs. */
     include?: string[];
+    /**
+     * Class names to always include in the generated kbach.css, even if no
+     * scan finds them literally in your source. Static extraction only ever
+     * sees complete class strings as they appear in your files — it can't
+     * evaluate `` `bg-${color}-${shade}` `` or similar runtime-built strings,
+     * because the actual value doesn't exist until the component renders (see
+     * useStyles()'s own docblock for the same limitation from the other
+     * direction). Same purpose as Tailwind's `safelist` config: list the
+     * complete class names explicitly, e.g. generated from the same
+     * color/shade arrays your component already loops over —
+     *
+     * ```js
+     * const families = ['red', 'blue', 'green'];
+     * const shades = [1, 2, 3];
+     * safelist: families.flatMap((f) => shades.map((s) => `bg-${f}-${s}`))
+     * ```
+     */
+    safelist?: string[];
 }
 declare function kbach(userConfigOrOptions?: FrameworkConfig | KbachPluginOptions): Plugin;
 

package/dist/vite-plugin.d.ts

@@ -150,6 +150,24 @@ interface KbachPluginOptions {
     framework?: FrameworkConfig;
     /** Directories to scan for class strings (relative to Vite root). Defaults to common source dirs. */
     include?: string[];
+    /**
+     * Class names to always include in the generated kbach.css, even if no
+     * scan finds them literally in your source. Static extraction only ever
+     * sees complete class strings as they appear in your files — it can't
+     * evaluate `` `bg-${color}-${shade}` `` or similar runtime-built strings,
+     * because the actual value doesn't exist until the component renders (see
+     * useStyles()'s own docblock for the same limitation from the other
+     * direction). Same purpose as Tailwind's `safelist` config: list the
+     * complete class names explicitly, e.g. generated from the same
+     * color/shade arrays your component already loops over —
+     *
+     * ```js
+     * const families = ['red', 'blue', 'green'];
+     * const shades = [1, 2, 3];
+     * safelist: families.flatMap((f) => shades.map((s) => `bg-${f}-${s}`))
+     * ```
+     */
+    safelist?: string[];
 }
 declare function kbach(userConfigOrOptions?: FrameworkConfig | KbachPluginOptions): Plugin;
 

package/dist/vite-plugin.js

@@ -3860,9 +3860,10 @@ function stripModifierPrefix(token) {
 }
 var DEFAULT_SCAN_DIRS = ["src", "app", "pages", "components", "views", "layouts"];
 function kbach(userConfigOrOptions) {
-  const isOptions = userConfigOrOptions != null && ("framework" in userConfigOrOptions || "include" in userConfigOrOptions);
+  const isOptions = userConfigOrOptions != null && ("framework" in userConfigOrOptions || "include" in userConfigOrOptions || "safelist" in userConfigOrOptions);
   const userConfig = isOptions ? userConfigOrOptions.framework : userConfigOrOptions;
   const includeDirs = (isOptions ? userConfigOrOptions.include : void 0) ?? DEFAULT_SCAN_DIRS;
+  const safelist = (isOptions ? userConfigOrOptions.safelist : void 0) ?? [];
   const cfg = buildConfig(userConfig ?? {});
   const screens = toNumericScreens(cfg.theme.screens ?? {});
   const screenKeys = Object.keys(cfg.theme.screens ?? {});
@@ -3895,6 +3896,17 @@ function kbach(userConfigOrOptions) {
     }
     fileTokens.set(key, tokens);
   }
+  const SAFELIST_KEY = "\0kbach-safelist";
+  function processSafelist() {
+    if (safelist.length === 0) return;
+    const tokens = new Set(safelist);
+    for (const tok of tokens) {
+      if (!tokenCSS.has(tok)) {
+        tokenCSS.set(tok, generateClassCSS(tok, cfg.theme, cfg.darkMode, screens));
+      }
+    }
+    fileTokens.set(SAFELIST_KEY, tokens);
+  }
   function scanProjectCssSelectors() {
     for (const dir of includeDirs) scanCssSelectorsInto((0, import_path.join)(root, dir), projectCssClasses);
   }
@@ -3992,6 +4004,7 @@ ${code}`,
       mainCSSFile = findKbachCSS(root);
       scanProjectCssSelectors();
       initialScan();
+      processSafelist();
       if (mainCSSFile) writeKbachToFile(mainCSSFile, generateCSS());
     },
     // Vite's `handleHotUpdate` hook only fires for `type === "update"` (plain

package/dist/vite-plugin.mjs

@@ -3824,9 +3824,10 @@ function stripModifierPrefix(token) {
 }
 var DEFAULT_SCAN_DIRS = ["src", "app", "pages", "components", "views", "layouts"];
 function kbach(userConfigOrOptions) {
-  const isOptions = userConfigOrOptions != null && ("framework" in userConfigOrOptions || "include" in userConfigOrOptions);
+  const isOptions = userConfigOrOptions != null && ("framework" in userConfigOrOptions || "include" in userConfigOrOptions || "safelist" in userConfigOrOptions);
   const userConfig = isOptions ? userConfigOrOptions.framework : userConfigOrOptions;
   const includeDirs = (isOptions ? userConfigOrOptions.include : void 0) ?? DEFAULT_SCAN_DIRS;
+  const safelist = (isOptions ? userConfigOrOptions.safelist : void 0) ?? [];
   const cfg = buildConfig(userConfig ?? {});
   const screens = toNumericScreens(cfg.theme.screens ?? {});
   const screenKeys = Object.keys(cfg.theme.screens ?? {});
@@ -3859,6 +3860,17 @@ function kbach(userConfigOrOptions) {
     }
     fileTokens.set(key, tokens);
   }
+  const SAFELIST_KEY = "\0kbach-safelist";
+  function processSafelist() {
+    if (safelist.length === 0) return;
+    const tokens = new Set(safelist);
+    for (const tok of tokens) {
+      if (!tokenCSS.has(tok)) {
+        tokenCSS.set(tok, generateClassCSS(tok, cfg.theme, cfg.darkMode, screens));
+      }
+    }
+    fileTokens.set(SAFELIST_KEY, tokens);
+  }
   function scanProjectCssSelectors() {
     for (const dir of includeDirs) scanCssSelectorsInto(join(root, dir), projectCssClasses);
   }
@@ -3956,6 +3968,7 @@ ${code}`,
       mainCSSFile = findKbachCSS(root);
       scanProjectCssSelectors();
       initialScan();
+      processSafelist();
       if (mainCSSFile) writeKbachToFile(mainCSSFile, generateCSS());
     },
     // Vite's `handleHotUpdate` hook only fires for `type === "update"` (plain

package/kbach-ui.md

@@ -120,6 +120,27 @@ kbach({
 })
 ```
 
+`kbach()` also accepts an options wrapper — `{ framework, include, safelist }` — instead of a bare framework config directly:
+
+```ts
+kbach({
+  framework: { darkMode: 'attribute', theme: { colors: { brand: { 6: '#6366f1' } } } },
+  include: ['src'],   // dirs to scan (relative to Vite root) — default: src, app, pages, components, views, layouts
+  safelist: [ /* see below */ ],
+})
+```
+
+**`safelist`** — class names to always include, even if no scan finds them. Static extraction only ever sees complete class strings as they appear in your source — it can't evaluate `` `bg-${family}-${shade}` `` or similar runtime-built strings, since the actual value doesn't exist until the component renders (this is exactly why `useStyles()` exists — see its own docs above — it resolves those to a real inline style instead). If you want a genuinely dynamic set of classes in the static file anyway, generate the full list yourself and pass it in — same purpose as Tailwind's own `safelist` config:
+
+```ts
+const families = ['red', 'blue', 'green' /* … */];
+const shades = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12];
+
+kbach({
+  safelist: families.flatMap((f) => shades.map((s) => `bg-${f}-${s}`)),
+})
+```
+
 Generated output format:
 ```css
 /* kbach:start */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kbach/ui",
-  "version": "0.1.0-beta.6",
+  "version": "0.1.0-beta.7",
   "description": "Tailwind-like utility classes and components for React — web, React Native, and Expo",
   "license": "MIT",
   "repository": {