@kbach/react 0.5.38 → 0.5.40

package/README.md

@@ -1,6 +1,6 @@
 # @kbach/react
 
-Tailwind-like utility classes for **React (web)**. Classes are converted to inline styles at render time through a custom JSX runtime — no stylesheet required. Responsive, dark mode, hover, and pseudo-element rules are injected as real CSS so they work with pure CSS cascading.
+Tailwind-like utility classes for **React (web)**. Classes are resolved to inline styles at render time through a custom JSX runtime — no separate stylesheet step required. Responsive, dark mode, hover, and pseudo-element rules are injected as real CSS so they work with the full CSS cascade.
 
 ```jsx
 /** @jsxImportSource @kbach/react */
@@ -9,7 +9,7 @@ Tailwind-like utility classes for **React (web)**. Classes are converted to inli
 <div className="bg-blue-7 hover:bg-blue-8 dark:bg-indigo-6 rounded-lg px-6 py-3" />
 <div className="bg-[#6366f1] p-[14px] rounded-[20px]" />
 <div className="group">
-  <span className="group-hover:text-blue-6 transition" />
+  <span className="opacity-0 group-hover:opacity-100 transition" />
 </div>
 ```
 
@@ -36,7 +36,7 @@ npm install @kbach/react
 
 **Vite**
 
-```js
+```ts
 // vite.config.ts
 import { defineConfig } from 'vite';
 import react from '@vitejs/plugin-react';
@@ -45,12 +45,12 @@ import { kbach } from '@kbach/react/vite';
 export default defineConfig({
   plugins: [
     react({ jsxImportSource: '@kbach/react' }),
-    kbach(), // generates app.css on every HMR event
+    kbach(), // generates CSS and writes it to your main CSS file
   ],
 });
 ```
 
-The `kbach()` Vite plugin scans your source files and writes generated CSS between `/* kbach:start */` / `/* kbach:end */` markers in your main CSS file (`src/index.css`, `app/app.css`, etc.). It rescans fresh on every HMR event so removed classes are immediately evicted.
+The `kbach()` Vite plugin scans your source files for class strings (including ternary expressions, template literals, and `clsx`/`cn` call patterns) and writes the generated CSS between `/* kbach:start */` / `/* kbach:end */` markers in your main CSS file (`src/index.css`, `app/app.css`, etc.). On HMR only the changed file is rescanned — unchanged class tokens reuse their cached CSS.
 
 **Babel**
 
@@ -85,20 +85,20 @@ export default function Root() {
 
 ## API
 
-### className prop
+### className / kb prop
 
-Works on any HTML element or React component once the JSX runtime is configured.
+Works on any HTML element or React component once the JSX runtime is configured. Both `className` and `kb` are equivalent — `kb` is shorter and avoids conflicts with library components that forward `className` to their own DOM elements.
 
 ```jsx
 <div className="bg-white dark:bg-gray-10 p-4 rounded-xl" />
-<p className="text-gray-10 dark:text-white text-lg font-bold" />
+<p kb="text-gray-10 dark:text-white text-lg font-bold" />
 <button className="bg-blue-7 hover:bg-blue-8 pressed:bg-blue-9 rounded-lg px-4 py-2" />
 <input className="caret-blue-6 focus:ring-2" />
 ```
 
 ### styled(Component, classes)
 
-Pre-style any component. Returns a new component that merges the base classes with any `kb` prop passed at use time. On web, the class string is forwarded as `className` so CSS rules (group-hover:, before:, print:, etc.) match the element.
+Pre-style any component. Returns a new component that merges the base classes with any `kb` prop passed at use time. On web, the class string is forwarded as `className` so CSS rules (`group-hover:`, `before:`, `print:`, etc.) match the element.
 
 ```jsx
 import { styled } from '@kbach/react';
@@ -116,22 +116,36 @@ const Button = styled(
 </Card>
 ```
 
-### useStyles(classes)
+### useStyles(classes, state?)
 
-Resolve classes to a style object inside a component.
+Resolve classes to a style object inside a component. Accepts a string, an array of strings (merged left-to-right), and an optional interaction state object.
 
 ```jsx
 import { useStyles } from '@kbach/react';
 
-function Badge() {
-  const style = useStyles('bg-blue-6 dark:bg-indigo-6 px-3 py-1 rounded-full');
-  return <span style={style}>New</span>;
-}
+// Basic
+const style = useStyles('bg-blue-6 dark:bg-indigo-6 px-3 py-1 rounded-full');
+
+// Multiple class strings merged
+const style = useStyles(['bg-white p-4', 'dark:bg-gray-9 rounded-xl']);
+
+// With interaction state
+const [pressed, setPressed] = useState(false);
+const style = useStyles('bg-blue-5 pressed:bg-blue-7 rounded-lg', { pressed });
+```
+
+### useResolvedStyle(classes)
+
+Returns the raw bucket map (`{ base, dark, hover, … }`) without flattening. Useful when you need to pass different buckets to different elements, or animate between states with `Animated`.
+
+```js
+const resolved = useResolvedStyle('bg-white dark:bg-gray-9 p-4');
+// { base: { backgroundColor: '#fff', padding: 16 }, dark: { backgroundColor: '#1f2937' } }
 ```
 
 ### kb(classes)
 
-Resolve classes outside a component (static contexts, etc.).
+Resolve classes outside a component (static contexts, `StyleSheet.create()`, etc.).
 
 ```js
 import { kb } from '@kbach/react';
@@ -172,25 +186,33 @@ const { mode, resolvedMode, isDark, setMode, toggle, config } = useTheme();
 
 ### useIsDark()
 
-Shorthand hook when you only need the dark-mode boolean.
-
 ```js
 import { useIsDark } from '@kbach/react';
-
 const isDark = useIsDark();
 ```
 
+### useBreakpoint() / useResponsive()
+
+```js
+import { useBreakpoint, useResponsive } from '@kbach/react';
+
+const bp = useBreakpoint(); // 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl'
+
+const { sm, md, lg } = useResponsive();
+const padding = lg ? 32 : sm ? 16 : 8;
+```
+
 ### useColors()
 
-Returns the active theme's color palette as a smart proxy. Supports shade access, the `/opacity` modifier, flat colors with opacity, and arbitrary CSS color manipulation.
+Returns the active theme's color palette as a smart proxy. Supports shade access, `/opacity` modifier, and arbitrary CSS color manipulation. Handles 3, 4, 6, and 8-digit hex values.
 
 ```js
 import { useColors } from '@kbach/react';
 
 const colors = useColors();
 
-colors.blue[6]           // '#6c87b6'
-colors.blue['6/50']      // 'rgba(108,135,182,0.5)'
+colors.blue[6]           // '#3b82f6'
+colors.blue['6/50']      // 'rgba(59,130,246,0.5)'
 colors.white             // '#ffffff'
 colors['white/20']       // 'rgba(255,255,255,0.2)'
 colors.alpha('#ff6b35', 60) // 'rgba(255,107,53,0.6)'
@@ -209,54 +231,73 @@ Drop-in toggle component.
 
 ## Modifiers
 
-Up to 3 modifiers can be chained in any order.
+Modifiers are chainable with no hard cap — as many as needed in any order:
+
+```jsx
+<div className="dark:sm:hover:focus:p-4" />
+<div className="dark:group-hover:not-disabled:text-blue-6" />
+```
 
-### Theme & interaction
+### Theme & mode
 
 | Modifier | Trigger |
 |---|---|
 | `dark:` | Dark mode active |
-| `light:` | Light mode active |
-| `hover:` | Mouse hover |
-| `pressed:` | Click / touch |
-| `focus:` | Focused |
-| `active:` | Active state |
-| `disabled:` | Disabled |
-| `checked:` | Checked (checkbox/radio) |
-| `visited:` | Visited link |
-| `focus-within:` | Focus inside element |
-| `focus-visible:` | Keyboard focus ring |
-
-Negated forms: `not-hover:`, `not-focus:`, `not-active:`, `not-pressed:`, `not-disabled:`, `not-checked:`, `not-visited:`
-
-### Structural
-
-| Modifier | Matches |
+| `not-dark:` / `light:` | Light mode active |
+| `not-light:` | Dark mode active (alias) |
+
+### Interactive — JS state + CSS pseudo
+
+| Modifier | Trigger |
+|---|---|
+| `hover:` / `not-hover:` | Mouse hover |
+| `focus:` / `not-focus:` | Focused |
+| `pressed:` / `not-pressed:` | Click / touch down |
+| `active:` / `not-active:` | Active state |
+| `disabled:` / `not-disabled:` | Disabled |
+| `checked:` / `not-checked:` | Checkbox / radio checked |
+| `visited:` / `not-visited:` | Visited link |
+| `placeholder:` | Placeholder text |
+
+### CSS-only pseudo-classes (structural)
+
+| Modifier | CSS |
 |---|---|
 | `first:` | `:first-child` |
 | `last:` | `:last-child` |
 | `odd:` | `:nth-child(odd)` |
 | `even:` | `:nth-child(even)` |
 | `only:` | `:only-child` |
+| `focus-within:` | `:focus-within` |
+| `focus-visible:` | `:focus-visible` |
 
-### Responsive
+### Pseudo-elements
 
-| Modifier | Min-width |
-|---|---|
-| `sm:` | 576 px |
-| `md:` | 768 px |
-| `lg:` | 1024 px |
-| `xl:` | 1280 px |
-| `2xl:` | 1536 px |
+```jsx
+<div className="before:content-['*'] before:text-red-6 relative" />
+<p className="first-letter:text-4xl first-letter:font-bold" />
+<input className="placeholder:text-gray-5" />
+<p className="selection:bg-blue-3" />
+```
 
-### Group / peer
+| Modifier | CSS |
+|---|---|
+| `before:` | `::before` |
+| `after:` | `::after` |
+| `selection:` | `::selection` |
+| `first-letter:` | `::first-letter` |
+| `first-line:` | `::first-line` |
+| `marker:` | `::marker` |
+| `placeholder:` | `::placeholder` |
 
-Mark an ancestor with `group` or `peer`, then style descendants with the modifier:
+### Group / peer ancestor selectors
 
 ```jsx
 <div className="group">
   <span className="opacity-0 group-hover:opacity-100 transition" />
 </div>
+<input className="peer" />
+<p className="peer-focus:text-blue-6" />
 ```
 
 | Modifier | Fires when |
@@ -266,37 +307,43 @@ Mark an ancestor with `group` or `peer`, then style descendants with the modifie
 | `peer-hover:` | Previous sibling `.peer` is hovered |
 | `peer-focus:` | Previous sibling `.peer` is focused |
 
-### Pseudo-elements
+### Responsive
+
+| Modifier | Min-width |
+|---|---|
+| `sm:` | 576 px |
+| `md:` | 768 px |
+| `lg:` | 1024 px |
+| `xl:` | 1280 px |
+| `2xl:` | 1536 px |
 
-Inject content or style structural parts of an element with real CSS:
+### Print
 
 ```jsx
-<div className="before:content-['*'] before:text-red-6 relative" />
-<p className="first-letter:text-4xl first-letter:font-bold" />
-<input className="placeholder:text-gray-5" />
-<p className="selection:bg-blue-3" />
+<div className="print:hidden" />
+<div className="print:text-black print:bg-white" />
 ```
 
-| Modifier | CSS |
+### Orientation & accessibility media
+
+| Modifier | Media query |
 |---|---|
-| `before:` | `::before` |
-| `after:` | `::after` |
-| `selection:` | `::selection` |
-| `first-letter:` | `::first-letter` |
-| `first-line:` | `::first-line` |
-| `marker:` | `::marker` |
-| `placeholder:` | `::placeholder` |
+| `landscape:` | `(orientation: landscape)` |
+| `portrait:` | `(orientation: portrait)` |
+| `motion-reduce:` | `(prefers-reduced-motion: reduce)` |
+| `motion-safe:` | `(prefers-reduced-motion: no-preference)` |
+| `contrast-more:` | `(prefers-contrast: more)` |
+| `contrast-less:` | `(prefers-contrast: less)` |
 
-### Print
+### Directionality
 
 ```jsx
-<div className="print:hidden" />
-<div className="print:text-black print:bg-white" />
+<div className="rtl:text-right ltr:text-left" />
 ```
 
-### Important modifier
+### Important
 
-Prefix any class with `!` to add `!important` to every CSS declaration it produces:
+Prefix any class with `!` to add `!important` to every declaration it produces:
 
 ```jsx
 <div className="!p-0 !m-0" />
@@ -365,76 +412,104 @@ module.exports = {
   darkMode: 'attribute', // 'attribute' | 'class' | 'media'
 
   theme: {
+    // Replace a theme section entirely
     colors: {
       brand: { 1: '#eff6ff', 6: '#3b82f6', 10: '#1e3a5f' },
     },
   },
 
   extend: {
-    theme: {
-      colors: { brand: { 6: '#6366f1' } },
-      spacing: { 18: '72px' },
-    },
+    // Add to defaults without replacing them
+    colors: { brand: { 6: '#6366f1' } },
+    spacing: { 18: '72px' },
+    screens: { '3xl': '1920px' },
   },
 
   plugins: [
-    ({ addUtility, theme }) => {
+    ({ addUtility, addVariant, theme }) => {
+      // Custom utility
       addUtility('border-brand', {
         borderColor: theme('colors.brand.6'),
         borderWidth: 2,
       });
+
+      // Custom variant — selector string (auto-converted to CSS rules)
+      addVariant('hocus', ':hover, :focus');
+      addVariant('supports-grid', '@media (display: grid)');
+      addVariant('dark-theme', '.dark-theme');
+
+      // Custom variant — full ModifierDef for JS-tracked interactive states
+      addVariant('long-press', {
+        pseudo: ':active',
+        jsBehavior: 'interactive',
+        jsMatch: (_, state) => !!state.longPressed,
+      });
     },
   ],
 };
 ```
 
-Apply at runtime:
+### Color aliases
 
-```js
-import { updateConfig } from '@kbach/react';
+Color values can reference other palette entries — chains up to 5 levels deep are resolved:
 
-updateConfig({ extend: { theme: { colors: { brand: { 6: '#6366f1' } } } } });
+```js
+extend: {
+  colors: {
+    primary: 'blue-6',          // → resolved hex of blue shade 6
+    brand: { 6: 'primary' },    // → follows through to blue-6's hex
+  },
+},
 ```
 
 ### Font Family
 
-Define custom font families and use them with `font-<name>`:
-
 ```js
 // kbach.config.js
 module.exports = {
   extend: {
     fontFamily: {
-      // shorthand: extend.fontFamily is equivalent to extend.theme.fontFamily
-      sans:        'CormorantGaramond_400Regular',
-      'sans-md':   'CormorantGaramond_500Medium',
-      'sans-semi': 'CormorantGaramond_600SemiBold',
-      'sans-bold': 'CormorantGaramond_700Bold',
+      sans:        'Inter_400Regular',
+      'sans-md':   'Inter_500Medium',
+      'sans-bold': 'Inter_700Bold',
     },
   },
 };
 ```
 
-Use them as utilities:
+Use as utilities:
 
 ```jsx
-<Text className="font-sans">Regular</Text>
-<Text className="font-sans-md">Medium</Text>
-<Text className="font-sans-bold">Bold</Text>
+<p className="font-sans">Regular</p>
+<p className="font-sans-md">Medium</p>
+<p className="font-sans-bold">Bold</p>
 ```
 
-**Global default font (web only):** When you set `fontFamily.sans` to anything other than `'System'`, Kbach automatically injects `body { font-family: <your-font> }` into the page — all text inherits it without needing `font-sans` on every element.
+**Global default font (web):** When `fontFamily.sans` is set to anything other than `'System'`, Kbach automatically injects `body { font-family: <your-font> }` — all text inherits it without `font-sans` on every element.
 
-**React Native:** CSS inheritance does not exist in RN. Apply `font-sans` (or your base font utility) to each `Text` component, or use `styled()` to create a pre-styled text component:
+Apply at runtime (e.g. from a server-side user preference):
 
-```jsx
-// Define once
-const Body = styled(Text, 'font-sans');
-const Heading = styled(Text, 'font-sans-bold text-2xl');
+```js
+import { updateConfig } from '@kbach/react';
 
-// Use everywhere
-<Body>Regular text</Body>
-<Heading>Title</Heading>
+updateConfig({ extend: { colors: { brand: { 6: '#6366f1' } } } });
+```
+
+## Custom responsive breakpoints
+
+Add breakpoints in `extend.screens` — they automatically register as new modifier names:
+
+```js
+// kbach.config.js
+module.exports = {
+  extend: {
+    screens: { '3xl': '1920px' },
+  },
+};
+```
+
+```jsx
+<div className="3xl:max-w-screen-3xl 3xl:mx-auto" />
 ```
 
 ## Full reference

package/dist/{chunk-EJFQKJPT.mjs → chunk-6NHHYHNV.mjs}

@@ -1,18 +1,22 @@
 import {
-  EMPTY_BREAKPOINTS,
+  EMPTY_BREAKPOINTS2 as EMPTY_BREAKPOINTS,
   InteractiveWrapper,
+  hasResponsiveBuckets,
   useConditionalWidth,
   useGlobalDarkMode
-} from "./chunk-W7UBSRE5.mjs";
+} from "./chunk-EYPBYQSB.mjs";
 import {
   flatten,
   getActiveBreakpoints,
   getConfig,
   getDefaultFontFamily,
+  getInteractiveModifiers,
+  getModeModifiers,
+  getResponsiveModifiers,
   isWeb,
   normalizeClassString,
   resolve
-} from "./chunk-NWVL4BES.mjs";
+} from "./chunk-IZ3W6G3V.mjs";
 
 // src/jsx-runtime.tsx
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
@@ -20,16 +24,6 @@ import { Fragment } from "react";
 
 // src/DarkWrapper.tsx
 import React from "react";
-var RESPONSIVE_MODS = /* @__PURE__ */ new Set(["sm", "md", "lg", "xl", "2xl"]);
-function hasResponsiveBuckets(resolved) {
-  for (const key of Object.keys(resolved)) {
-    if (key === "base") continue;
-    for (const mod of key.split(":")) {
-      if (RESPONSIVE_MODS.has(mod)) return true;
-    }
-  }
-  return false;
-}
 var DarkWrapper = React.forwardRef(
   function DarkWrapper2({ Component, resolvedStyle, style: styleProp, children, ...rest }, ref) {
     const isDark = useGlobalDarkMode();
@@ -77,51 +71,39 @@ function stripWebOnlyProps(s) {
 }
 
 // src/jsx-runtime.tsx
-var INTERACTIVE_MODS = /* @__PURE__ */ new Set([
-  "hover",
-  "not-hover",
-  "focus",
-  "not-focus",
-  "active",
-  "not-active",
-  "pressed",
-  "not-pressed",
-  "disabled",
-  "not-disabled",
-  "checked",
-  "not-checked",
-  "visited",
-  "not-visited",
-  "placeholder",
-  "group-hover",
-  "group-focus",
-  "peer-hover",
-  "peer-focus"
-  // focus-within / focus-visible / first / last / odd / even / only are CSS-only —
-  // they have no JS state to track, so they don't need InteractiveWrapper.
-]);
-var RESPONSIVE_MODS2 = /* @__PURE__ */ new Set(["sm", "md", "lg", "xl", "2xl"]);
-var MODE_MODS_JSX = /* @__PURE__ */ new Set(["dark", "light", "not-dark", "not-light"]);
+var _cachedDefaultFont = void 0;
+var _defaultFontVersion = 0;
+var _lastFontVersion = -1;
+function _invalidateDefaultFontCache() {
+  _defaultFontVersion++;
+}
+function getCachedDefaultFont() {
+  if (_lastFontVersion !== _defaultFontVersion) {
+    _cachedDefaultFont = getDefaultFontFamily();
+    _lastFontVersion = _defaultFontVersion;
+  }
+  return _cachedDefaultFont;
+}
+var _bucketModsCache = /* @__PURE__ */ new WeakMap();
 function bucketMods(resolved) {
+  const cached = _bucketModsCache.get(resolved);
+  if (cached) return cached;
+  const interactiveMods = getInteractiveModifiers();
+  const modeMods = getModeModifiers();
+  const responsiveMods = getResponsiveModifiers();
   let interactive = false;
   let modeOrResponsive = false;
   for (const key of Object.keys(resolved)) {
     if (key === "base") continue;
-    const parts = key.split(":");
-    for (const mod of parts) {
-      if (INTERACTIVE_MODS.has(mod)) {
-        interactive = true;
-        break;
-      }
-    }
-    for (const mod of parts) {
-      if (MODE_MODS_JSX.has(mod) || RESPONSIVE_MODS2.has(mod)) {
-        modeOrResponsive = true;
-        break;
-      }
+    for (const mod of key.split(":")) {
+      if (!interactive && interactiveMods.has(mod)) interactive = true;
+      if (!modeOrResponsive && (modeMods.has(mod) || responsiveMods.has(mod))) modeOrResponsive = true;
     }
+    if (interactive && modeOrResponsive) break;
   }
-  return { interactive, modeOrResponsive };
+  const result = { interactive, modeOrResponsive };
+  _bucketModsCache.set(resolved, result);
+  return result;
 }
 var CONSUMED_PROPS = /* @__PURE__ */ new Set(["className", "kb", "__kbachStyles", "__kbachClasses"]);
 function omitConsumed(props) {
@@ -196,10 +178,8 @@ function processElement(type, rawProps, key, isStaticChildren) {
   const { className, kb: kbProp, __kbachStyles, __kbachClasses } = rawProps;
   const classStr = className ?? kbProp ?? __kbachClasses;
   if (!classStr && !__kbachStyles) {
-    const defaultFont = getDefaultFontFamily();
-    if (!defaultFont) {
-      return makeElement(isStaticChildren, type, rawProps, key);
-    }
+    const defaultFont = getCachedDefaultFont();
+    if (!defaultFont) return makeElement(isStaticChildren, type, rawProps, key);
     const { style: userStyle2, ...passProps2 } = omitConsumed(rawProps);
     const finalStyle2 = userStyle2 ? Array.isArray(userStyle2) ? { fontFamily: defaultFont, ...Object.assign({}, ...userStyle2) } : { fontFamily: defaultFont, ...userStyle2 } : { fontFamily: defaultFont };
     return makeElement(isStaticChildren, type, { ...passProps2, style: finalStyle2 }, key);
@@ -248,6 +228,7 @@ function jsxs(type, props, key) {
 
 export {
   Fragment,
+  _invalidateDefaultFontCache,
   jsx,
   jsxs
 };

package/dist/{chunk-W7UBSRE5.mjs → chunk-EYPBYQSB.mjs}

@@ -2,9 +2,10 @@ import {
   flatten,
   getActiveBreakpoints,
   getGlobalWidth,
+  getResponsiveModifiers,
   isWeb,
   subscribeGlobalWidth
-} from "./chunk-NWVL4BES.mjs";
+} from "./chunk-IZ3W6G3V.mjs";
 
 // src/core/darkModeStore.ts
 var KEY = "__kbach_dark_store__";
@@ -107,23 +108,26 @@ function useConditionalWidth(active) {
   );
 }
 
-// src/InteractiveWrapper.tsx
-function chain(original, extra) {
-  return (...args) => {
-    original?.(...args);
-    extra();
-  };
-}
-var RESPONSIVE_MODS = /* @__PURE__ */ new Set(["sm", "md", "lg", "xl", "2xl"]);
+// src/shared-utils.ts
 function hasResponsiveBuckets(resolved) {
+  const responsiveMods = getResponsiveModifiers();
   for (const key of Object.keys(resolved)) {
     if (key === "base") continue;
     for (const mod of key.split(":")) {
-      if (RESPONSIVE_MODS.has(mod)) return true;
+      if (responsiveMods.has(mod)) return true;
     }
   }
   return false;
 }
+var EMPTY_BREAKPOINTS2 = /* @__PURE__ */ new Set();
+
+// src/InteractiveWrapper.tsx
+function chain(original, extra) {
+  return (...args) => {
+    original?.(...args);
+    extra();
+  };
+}
 var InteractiveWrapper = forwardRef(
   function InteractiveWrapper2({
     Component,
@@ -219,6 +223,8 @@ export {
   EMPTY_BREAKPOINTS,
   useGlobalWidth,
   useConditionalWidth,
+  hasResponsiveBuckets,
+  EMPTY_BREAKPOINTS2,
   useGlobalDarkMode,
   InteractiveWrapper
 };