@kbach/react 0.2.7 → 0.2.9

package/README.md

@@ -119,14 +119,14 @@ function Badge() {
 }
 ```
 
-### tw(classes)
+### kb(classes)
 
-Resolve classes outside a component (static contexts).
+Resolve classes outside a component (static contexts, StyleSheet.create, etc.).
 
 ```js
-import { tw } from '@kbach/react';
+import { kb } from '@kbach/react';
 
-const cardStyle = tw('bg-white p-4 rounded-xl') as React.CSSProperties;
+const cardStyle = kb('bg-white p-4 rounded-xl') as React.CSSProperties;
 ```
 
 ### cx(...classes)
@@ -148,16 +148,59 @@ import { cx } from '@kbach/react';
 ```js
 import { useTheme } from '@kbach/react';
 
-const { mode, resolvedMode, isDark, setMode, toggle } = useTheme();
+const { mode, resolvedMode, isDark, setMode, toggle, config } = useTheme();
 ```
 
 | Value | Type | Description |
 |---|---|---|
-| mode | `'light' \| 'dark' \| 'system'` | User-selected mode |
-| resolvedMode | `'light' \| 'dark'` | Resolved after system lookup |
-| isDark | boolean | Shorthand for `resolvedMode === 'dark'` |
-| setMode | function | Set mode explicitly |
-| toggle | function | Toggle between light and dark |
+| `mode` | `'light' \| 'dark' \| 'system'` | User-selected mode |
+| `resolvedMode` | `'light' \| 'dark'` | Resolved after system lookup |
+| `isDark` | `boolean` | Shorthand for `resolvedMode === 'dark'` |
+| `setMode` | `fn` | Set mode explicitly |
+| `toggle` | `fn` | Toggle between light and dark |
+| `config` | `ResolvedConfig` | Full resolved config (theme, darkMode, plugins) |
+
+### useIsDark()
+
+Shorthand hook when you only need the dark-mode boolean.
+
+```js
+import { useIsDark } from '@kbach/react';
+
+const isDark = useIsDark();
+```
+
+### 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.
+
+```js
+import { useColors } from '@kbach/react';
+
+const colors = useColors();
+
+// Shade access
+colors.blue[6]           // '#6c87b6'
+colors.red[11]           // '#3e0606'
+
+// Shade + opacity (0–100)
+colors.blue['6/50']      // 'rgba(108,135,182,0.5)'
+colors.slate['3/10']     // 'rgba(221,227,242,0.1)'
+
+// Flat colors
+colors.white             // '#ffffff'
+colors.transparent       // 'transparent'
+
+// Flat color + opacity
+colors['white/20']       // 'rgba(255,255,255,0.2)'
+colors['black/80']       // 'rgba(0,0,0,0.8)'
+
+// Arbitrary CSS color with opacity
+colors.alpha('#ff6b35', 60)           // 'rgba(255,107,53,0.6)'
+colors.alpha('rgb(100,200,100)', 30)  // 'rgba(100,200,100,0.3)'
+```
+
+Common uses: chart libraries that need raw hex values, dynamic inline styles, color pickers that mirror the theme palette.
 
 ### ThemeToggle
 

package/dist/{chunk-QMJ4XUJA.mjs → chunk-Q5RMVTAU.mjs}

@@ -5,7 +5,7 @@ import {
   isWeb,
   resolve,
   useGlobalDarkMode
-} from "./chunk-LYGD2GSW.mjs";
+} from "./chunk-V5KHX4CZ.mjs";
 
 // src/jsx-runtime.tsx
 import { jsx as _jsx, jsxs as _jsxs, Fragment } from "react/jsx-runtime";

package/dist/{chunk-LYGD2GSW.mjs → chunk-V5KHX4CZ.mjs}

@@ -529,6 +529,13 @@ function escapeCSSSelector(cls) {
 }
 
 // src/core/parser.ts
+var PLUGIN_MODIFIERS = /* @__PURE__ */ new Set();
+function registerModifier(name) {
+  PLUGIN_MODIFIERS.add(name);
+}
+function clearPluginModifiers() {
+  PLUGIN_MODIFIERS.clear();
+}
 var MODIFIERS = /* @__PURE__ */ new Set([
   // Theme
   "dark",
@@ -958,7 +965,7 @@ function parseClass(className) {
     const colonIdx = findOuterColon(remaining);
     if (colonIdx === -1) break;
     const candidate = remaining.slice(0, colonIdx);
-    if (MODIFIERS.has(candidate)) {
+    if (MODIFIERS.has(candidate) || PLUGIN_MODIFIERS.has(candidate)) {
       modifiers.push(candidate);
       remaining = remaining.slice(colonIdx + 1);
     } else {
@@ -1424,43 +1431,64 @@ var RESOLVERS = {
   // ── Border width ───────────────────────────────────────────────────────────
   border: ({ value, isArbitrary }, { colors, borderWidth, spacing }) => {
     if (!value) return { borderWidth: borderWidth["DEFAULT"] ?? 1 };
-    const color = resolveColor(value, colors, isArbitrary);
-    if (color) return { borderColor: color };
     if (isArbitrary) {
       const w2 = toNativeValue(value);
-      return { borderWidth: typeof w2 === "number" ? w2 : 1 };
+      if (typeof w2 === "number") return { borderWidth: w2 };
+      return { borderColor: value };
     }
+    const color = resolveColor(value, colors, false);
+    if (color) return { borderColor: color };
     const w = borderWidth[value] ?? spacing[value];
     if (w !== void 0) return { borderWidth: typeof w === "number" ? w : parseFloat(String(w)) };
     return null;
   },
   "border-t": ({ value, isArbitrary }, { colors, borderWidth }) => {
     if (!value) return { borderTopWidth: 1 };
-    const color = resolveColor(value, colors, isArbitrary);
+    if (isArbitrary) {
+      const w2 = toNativeValue(value);
+      if (typeof w2 === "number") return { borderTopWidth: w2 };
+      return { borderTopColor: value };
+    }
+    const color = resolveColor(value, colors, false);
     if (color) return { borderTopColor: color };
-    const w = borderWidth[value] ?? (isArbitrary ? toNativeValue(value) : null);
-    return w !== null ? { borderTopWidth: typeof w === "number" ? w : parseFloat(String(w)) } : null;
+    const w = borderWidth[value];
+    return w !== void 0 ? { borderTopWidth: w } : null;
   },
   "border-r": ({ value, isArbitrary }, { colors, borderWidth }) => {
     if (!value) return { borderRightWidth: 1 };
-    const color = resolveColor(value, colors, isArbitrary);
+    if (isArbitrary) {
+      const w2 = toNativeValue(value);
+      if (typeof w2 === "number") return { borderRightWidth: w2 };
+      return { borderRightColor: value };
+    }
+    const color = resolveColor(value, colors, false);
     if (color) return { borderRightColor: color };
-    const w = borderWidth[value] ?? (isArbitrary ? toNativeValue(value) : null);
-    return w !== null ? { borderRightWidth: typeof w === "number" ? w : parseFloat(String(w)) } : null;
+    const w = borderWidth[value];
+    return w !== void 0 ? { borderRightWidth: w } : null;
   },
   "border-b": ({ value, isArbitrary }, { colors, borderWidth }) => {
     if (!value) return { borderBottomWidth: 1 };
-    const color = resolveColor(value, colors, isArbitrary);
+    if (isArbitrary) {
+      const w2 = toNativeValue(value);
+      if (typeof w2 === "number") return { borderBottomWidth: w2 };
+      return { borderBottomColor: value };
+    }
+    const color = resolveColor(value, colors, false);
     if (color) return { borderBottomColor: color };
-    const w = borderWidth[value] ?? (isArbitrary ? toNativeValue(value) : null);
-    return w !== null ? { borderBottomWidth: typeof w === "number" ? w : parseFloat(String(w)) } : null;
+    const w = borderWidth[value];
+    return w !== void 0 ? { borderBottomWidth: w } : null;
   },
   "border-l": ({ value, isArbitrary }, { colors, borderWidth }) => {
     if (!value) return { borderLeftWidth: 1 };
-    const color = resolveColor(value, colors, isArbitrary);
+    if (isArbitrary) {
+      const w2 = toNativeValue(value);
+      if (typeof w2 === "number") return { borderLeftWidth: w2 };
+      return { borderLeftColor: value };
+    }
+    const color = resolveColor(value, colors, false);
     if (color) return { borderLeftColor: color };
-    const w = borderWidth[value] ?? (isArbitrary ? toNativeValue(value) : null);
-    return w !== null ? { borderLeftWidth: typeof w === "number" ? w : parseFloat(String(w)) } : null;
+    const w = borderWidth[value];
+    return w !== void 0 ? { borderLeftWidth: w } : null;
   },
   // ── Border radius ──────────────────────────────────────────────────────────
   rounded: ({ value, isArbitrary }, { borderRadius }) => {
@@ -1525,7 +1553,6 @@ var RESOLVERS = {
     return { flexShrink: isNaN(n) ? 1 : n };
   },
   order: ({ value, isArbitrary }, _) => {
-    if (isArbitrary) return { order: parseInt(value) };
     const n = parseInt(value);
     return isNaN(n) ? null : { order: n };
   },
@@ -1573,9 +1600,15 @@ var RESOLVERS = {
   },
   // ── Z-index ────────────────────────────────────────────────────────────────
   z: ({ value, isArbitrary }, { zIndex }) => {
-    if (isArbitrary) return { zIndex: parseInt(value) };
+    if (isArbitrary) {
+      const n2 = parseInt(value);
+      return isNaN(n2) ? null : { zIndex: n2 };
+    }
     const v = zIndex[value];
-    if (v !== void 0) return { zIndex: v };
+    if (v !== void 0) {
+      if (v === "auto") return isWeb ? { zIndex: "auto" } : null;
+      return { zIndex: v };
+    }
     const n = parseInt(value);
     return isNaN(n) ? null : { zIndex: n };
   },
@@ -1618,25 +1651,30 @@ var RESOLVERS = {
     return shadow[key] ?? null;
   },
   // ── Scale ──────────────────────────────────────────────────────────────────
+  // Non-arbitrary: scale-150 → value='150' → 150/100 = 1.5
+  // Arbitrary:     scale-[1.5] → value='1.5' → used as-is (already the factor)
   scale: ({ value, isArbitrary }) => {
-    const n = isArbitrary ? parseFloat(value) / 100 : parseFloat(value) / 100;
+    const n = isArbitrary ? parseFloat(value) : parseFloat(value) / 100;
     if (isNaN(n)) return null;
     return isWeb ? { transform: `scale(${n})` } : { transform: [{ scale: n }] };
   },
   "scale-x": ({ value, isArbitrary }) => {
-    const n = isArbitrary ? parseFloat(value) / 100 : parseFloat(value) / 100;
+    const n = isArbitrary ? parseFloat(value) : parseFloat(value) / 100;
     if (isNaN(n)) return null;
     return isWeb ? { transform: `scaleX(${n})` } : { transform: [{ scaleX: n }] };
   },
   "scale-y": ({ value, isArbitrary }) => {
-    const n = isArbitrary ? parseFloat(value) / 100 : parseFloat(value) / 100;
+    const n = isArbitrary ? parseFloat(value) : parseFloat(value) / 100;
     if (isNaN(n)) return null;
     return isWeb ? { transform: `scaleY(${n})` } : { transform: [{ scaleY: n }] };
   },
   // ── Rotate ─────────────────────────────────────────────────────────────────
   rotate: ({ value, negative, isArbitrary }) => {
-    const raw = isArbitrary ? value : `${value}deg`;
-    const deg = parseFloat(raw);
+    if (isArbitrary) {
+      const finalValue = negative ? `-${value}` : value;
+      return isWeb ? { transform: `rotate(${finalValue})` } : { transform: [{ rotate: finalValue }] };
+    }
+    const deg = parseFloat(value);
     if (isNaN(deg)) return null;
     const finalDeg = negative ? -deg : deg;
     return isWeb ? { transform: `rotate(${finalDeg}deg)` } : { transform: [{ rotate: `${finalDeg}deg` }] };
@@ -1645,18 +1683,31 @@ var RESOLVERS = {
   "translate-x": ({ value, negative, isArbitrary }, { spacing }) => {
     const v = resolveSpacing(value, negative, spacing, isArbitrary);
     if (v === null) return null;
-    return isWeb ? { transform: `translateX(${v})` } : { transform: [{ translateX: typeof v === "string" ? parseFloat(v) : v }] };
+    if (isWeb) return { transform: `translateX(${v})` };
+    if (typeof v === "string") {
+      const n = parseFloat(v);
+      return isNaN(n) ? null : { transform: [{ translateX: n }] };
+    }
+    return { transform: [{ translateX: v }] };
   },
   "translate-y": ({ value, negative, isArbitrary }, { spacing }) => {
     const v = resolveSpacing(value, negative, spacing, isArbitrary);
     if (v === null) return null;
-    return isWeb ? { transform: `translateY(${v})` } : { transform: [{ translateY: typeof v === "string" ? parseFloat(v) : v }] };
+    if (isWeb) return { transform: `translateY(${v})` };
+    if (typeof v === "string") {
+      const n = parseFloat(v);
+      return isNaN(n) ? null : { transform: [{ translateY: n }] };
+    }
+    return { transform: [{ translateY: v }] };
   },
   // ── Aspect ratio ───────────────────────────────────────────────────────────
   aspect: ({ value, isArbitrary }) => {
     if (isArbitrary) return { aspectRatio: value };
     const presets = { auto: "auto", square: 1, video: 16 / 9 };
-    return value in presets ? { aspectRatio: presets[value] } : null;
+    if (!(value in presets)) return null;
+    const v = presets[value];
+    if (v === "auto") return isWeb ? { aspectRatio: "auto" } : null;
+    return { aspectRatio: v };
   },
   // ── Transition (web-only; use Animated API on native) ─────────────────────
   transition: ({ value }) => {
@@ -1733,18 +1784,25 @@ var RESOLVERS = {
   }
 };
 function resolveUtility(parsed, theme) {
-  if (!parsed.value && parsed.utility in STANDALONE) {
-    return STANDALONE[parsed.utility] ?? null;
+  if (!parsed.value) {
+    if (parsed.utility in PLUGIN_STANDALONE) return PLUGIN_STANDALONE[parsed.utility] ?? null;
+    if (parsed.utility in STANDALONE) return STANDALONE[parsed.utility] ?? null;
   }
-  const resolver = RESOLVERS[parsed.utility];
+  const resolver = PLUGIN_RESOLVERS[parsed.utility] ?? RESOLVERS[parsed.utility];
   if (resolver) return resolver(parsed, theme);
   return null;
 }
-function getStandaloneMap() {
-  return STANDALONE;
+var PLUGIN_STANDALONE = {};
+var PLUGIN_RESOLVERS = {};
+function clearPluginUtilities() {
+  for (const key of Object.keys(PLUGIN_STANDALONE)) delete PLUGIN_STANDALONE[key];
+  for (const key of Object.keys(PLUGIN_RESOLVERS)) delete PLUGIN_RESOLVERS[key];
+}
+function getPluginStandaloneMap() {
+  return PLUGIN_STANDALONE;
 }
-function getResolverMap() {
-  return RESOLVERS;
+function getPluginResolverMap() {
+  return PLUGIN_RESOLVERS;
 }
 
 // src/core/cache.ts
@@ -1797,8 +1855,42 @@ function getStyleEl() {
 function injectRule(rule) {
   if (_injectedRules.has(rule)) return;
   _injectedRules.add(rule);
-  getStyleEl().sheet?.insertRule(rule, getStyleEl().sheet.cssRules.length);
+  try {
+    getStyleEl().sheet?.insertRule(rule, getStyleEl().sheet.cssRules.length);
+  } catch {
+  }
 }
+var MODIFIER_TO_PSEUDO = {
+  hover: ":hover",
+  focus: ":focus",
+  "focus-within": ":focus-within",
+  "focus-visible": ":focus-visible",
+  active: ":active",
+  pressed: ":active",
+  disabled: ":disabled",
+  checked: ":checked",
+  visited: ":visited",
+  placeholder: "::placeholder",
+  first: ":first-child",
+  last: ":last-child",
+  odd: ":nth-child(odd)",
+  even: ":nth-child(even)",
+  only: ":only-child",
+  "not-hover": ":not(:hover)",
+  "not-focus": ":not(:focus)",
+  "not-active": ":not(:active)",
+  "not-pressed": ":not(:active)",
+  "not-disabled": ":not(:disabled)",
+  "not-checked": ":not(:checked)",
+  "not-visited": ":not(:visited)"
+};
+var GROUP_PEER_PREFIX = {
+  "group-hover": ".group:hover",
+  "group-focus": ".group:focus",
+  "peer-hover": ".peer:hover ~",
+  "peer-focus": ".peer:focus ~"
+};
+var MODE_MODS = /* @__PURE__ */ new Set(["dark", "light", "not-dark", "not-light"]);
 function injectClassRule(cls, bucketKey, styles, darkMode) {
   const cssDecls = styleValueToCSS(styles);
   if (!cssDecls) return;
@@ -1808,10 +1900,14 @@ function injectClassRule(cls, bucketKey, styles, darkMode) {
     return;
   }
   const mods = bucketKey.split(":");
-  const pseudos = mods.filter((m) => !["dark", "light"].includes(m));
-  const hasDark = mods.includes("dark");
-  const pseudoSuffix = pseudos.map((p) => `:${p}`).join("");
-  const selector = `.${escaped}${pseudoSuffix}`;
+  const hasDark = mods.includes("dark") || mods.includes("not-light");
+  const hasLight = mods.includes("light") || mods.includes("not-dark");
+  const ancestorMods = mods.filter((m) => m in GROUP_PEER_PREFIX);
+  const pseudoMods = mods.filter((m) => !MODE_MODS.has(m) && !(m in GROUP_PEER_PREFIX));
+  const pseudoSuffix = pseudoMods.map((p) => MODIFIER_TO_PSEUDO[p] ?? `:${p}`).join("");
+  const elementSelector = `.${escaped}${pseudoSuffix}`;
+  const ancestorPrefix = ancestorMods.length ? ancestorMods.map((m) => GROUP_PEER_PREFIX[m]).join(" ") + " " : "";
+  const selector = `${ancestorPrefix}${elementSelector}`;
   let rule;
   if (hasDark) {
     if (darkMode === "media") {
@@ -1821,13 +1917,54 @@ function injectClassRule(cls, bucketKey, styles, darkMode) {
     } else {
       rule = `[data-theme="dark"] ${selector} { ${cssDecls} }`;
     }
+  } else if (hasLight) {
+    if (darkMode === "media") {
+      rule = `@media (prefers-color-scheme: light) { ${selector} { ${cssDecls} } }`;
+    } else if (darkMode === "class") {
+      rule = `:not(.dark) ${selector} { ${cssDecls} }`;
+    } else {
+      rule = `[data-theme="light"] ${selector} { ${cssDecls} }`;
+    }
   } else {
     rule = `${selector} { ${cssDecls} }`;
   }
   injectRule(rule);
 }
+var RN_ONLY_PROPS = /* @__PURE__ */ new Set([
+  "shadowColor",
+  "shadowOffset",
+  "shadowOpacity",
+  "shadowRadius",
+  "elevation",
+  "includeFontPadding",
+  "textAlignVertical",
+  "writingDirection"
+]);
+var CSS_UNITLESS = /* @__PURE__ */ new Set([
+  "opacity",
+  "fontWeight",
+  "flex",
+  "flexGrow",
+  "flexShrink",
+  "order",
+  "zIndex",
+  "aspectRatio",
+  "columnCount",
+  "lineHeight"
+]);
 function styleValueToCSS(styles) {
-  return Object.entries(styles).filter(([, v]) => v !== void 0 && v !== null && typeof v !== "object").map(([prop, val]) => `${camelToKebab(prop)}: ${val}`).join("; ");
+  return Object.entries(styles).filter(
+    ([prop, v]) => v !== void 0 && v !== null && typeof v !== "object" && !RN_ONLY_PROPS.has(prop)
+  ).map(([prop, val]) => {
+    const cssProp = camelToKebab(prop);
+    let cssVal;
+    if (typeof val === "number") {
+      cssVal = val === 0 || CSS_UNITLESS.has(prop) ? String(val) : `${val}px`;
+    } else {
+      cssVal = String(val);
+    }
+    return `${cssProp}: ${cssVal}`;
+  }).join("; ");
 }
 function camelToKebab(str) {
   return str.replace(/([A-Z])/g, "-$1").toLowerCase();
@@ -1913,6 +2050,9 @@ function matchesMods(mods, isDark, state) {
     }
   });
 }
+function clearCache() {
+  styleCache.clear();
+}
 
 // src/core/config.ts
 function deepMerge(base, override) {
@@ -1968,20 +2108,24 @@ function buildConfig(userConfig) {
     theme,
     plugins: userConfig.plugins ?? []
   };
+  clearPluginUtilities();
+  clearPluginModifiers();
+  const pluginAPI = makePluginAPI(resolved.theme);
   for (const plugin of resolved.plugins) {
-    plugin(makePluginAPI(resolved.theme));
+    plugin(pluginAPI);
   }
   return resolved;
 }
 function makePluginAPI(theme) {
-  const standalone = getStandaloneMap();
-  const resolvers = getResolverMap();
+  const standalone = getPluginStandaloneMap();
+  const resolvers = getPluginResolverMap();
   return {
     addUtility(name, styles) {
       standalone[name] = styles;
     },
-    addVariant(name, _selector) {
-      customVariants[name] = _selector;
+    addVariant(name, selector) {
+      customVariants[name] = selector;
+      registerModifier(name);
     },
     theme(path, defaultValue) {
       const parts = path.replace(/\[([^\]]+)\]/g, ".$1").split(".");
@@ -2005,6 +2149,7 @@ function onConfigChange(listener) {
 function updateConfig(userConfig) {
   const store = getConfigStore();
   store.resolved = buildConfig(userConfig);
+  clearCache();
   for (const listener of store.listeners) {
     listener(store.resolved);
   }
@@ -2117,8 +2262,8 @@ var InteractiveWrapper = forwardRef(
       ...restWithoutChildren,
       style: finalStyle,
       ...isWeb && className ? { className } : {},
-      onPressIn: handlePressIn,
-      onPressOut: handlePressOut,
+      // onPressIn / onPressOut are React Native-only; skip on web to avoid DOM warnings.
+      ...isWeb ? {} : { onPressIn: handlePressIn, onPressOut: handlePressOut },
       onMouseEnter: handleMouseEnter,
       onMouseLeave: handleMouseLeave,
       onFocus: handleFocus,

package/dist/index.d.mts

@@ -139,6 +139,25 @@ interface ThemeContextValue {
 }
 declare const ThemeContext: React.Context<ThemeContextValue | null>;
 declare function useTheme(): ThemeContextValue;
+declare function useIsDark(): boolean;
+
+interface ColorScale {
+    /** `colors.blue[6]` → raw hex string */
+    readonly [shade: number]: string;
+    /** `colors.blue['6/50']` → shade 6 at 50% opacity */
+    readonly [key: string]: string;
+}
+interface ColorsAPI {
+    /** Named color scale (e.g. `colors.blue`) or flat value (e.g. `colors.white`) */
+    readonly [color: string]: string | ColorScale | ColorsAPI['alpha'];
+    /** Flat color with opacity shorthand: `colors['white/50']` */
+    /** Apply opacity to any CSS color string.
+     *  `colors.alpha('#3b82f6', 50)` → `'rgba(59,130,246,0.5)'`
+     *  `colors.alpha('rgb(0,0,0)', 10)` → `'rgba(0,0,0,0.1)'` */
+    alpha(color: string, opacity: number): string;
+}
+declare function wrapColors(rawColors: ThemeColors): ColorsAPI;
+declare function useColors(): ColorsAPI;
 
 interface ThemeProviderProps {
     children: ReactNode;
@@ -249,7 +268,7 @@ declare function useResolvedStyle(classString: string | string[]): ResolvedStyle
 
 /**
  * Subscribe to the global dark-mode store with React's concurrent-safe
- * useSyncExternalStore so that any component using className/tw re-renders
+ * useSyncExternalStore so that any component using className/kb re-renders
  * immediately when the theme changes — without needing ThemeContext.
  */
 declare function useGlobalDarkMode(): boolean;
@@ -272,7 +291,7 @@ interface InteractiveWrapperProps {
     onBlur?: (...args: any[]) => void;
 }
 /**
- * Thin wrapper rendered automatically by the JSX runtime whenever a className/tw
+ * Thin wrapper rendered automatically by the JSX runtime whenever a className/kb
  * string contains interactive modifiers (hover:, pressed:, focus:, active:, …).
  *
  * Manages interaction state locally and flattens the correct style bucket on
@@ -291,20 +310,20 @@ declare const InteractiveWrapper: React__default.ForwardRefExoticComponent<Inter
  *
  * ```ts
  * // Inside a component use useStyles() instead.
- * // tw() is useful for StyleSheet.create() calls and static values.
+ * // kb() is useful for StyleSheet.create() calls and static values.
  *
  * const styles = StyleSheet.create({
- *   container: tw('flex-1 bg-white p-4') as any,
+ *   container: kb('flex-1 bg-white p-4') as any,
  * });
  *
  * // Web: use as className
- * <div className={tw('bg-white dark:bg-gray-900 p-4') as string} />
+ * <div className={kb('bg-white dark:bg-gray-900 p-4') as string} />
  * ```
  *
  * @param classString   Space-separated utility classes
  * @param isDark        Whether dark mode is active (default: false)
  */
-declare function tw(classString: string, isDark?: boolean): StyleValue | string;
+declare function kb(classString: string, isDark?: boolean): StyleValue | string;
 /**
  * Conditionally join class names. Falsy values are ignored.
  *
@@ -315,4 +334,4 @@ declare function tw(classString: string, isDark?: boolean): StyleValue | string;
  */
 declare function cx(...classes: Array<string | false | null | undefined>): string;
 
-export { type FrameworkConfig, type InteractionState, InteractiveWrapper, type InteractiveWrapperProps, type ParsedClass, type PluginAPI, type ResolvedConfig, type ResolvedStyle, type StyleValue, type StyledProps, type ThemeConfig, ThemeContext, type ThemeContextValue, type ThemeMode, ThemeProvider, type ThemeProviderProps, ThemeToggle, type ThemeToggleProps, type ToggleVariant, buildConfig, cx, defaultColors, defaultTheme, flatten, getConfig, parseClass, parseClasses, resolve, styled, tw, updateConfig, useGlobalDarkMode, useResolvedStyle, useStyles, useTheme };
+export { type ColorScale, type ColorsAPI, type FrameworkConfig, type InteractionState, InteractiveWrapper, type InteractiveWrapperProps, type ParsedClass, type PluginAPI, type ResolvedConfig, type ResolvedStyle, type StyleValue, type StyledProps, type ThemeConfig, ThemeContext, type ThemeContextValue, type ThemeMode, ThemeProvider, type ThemeProviderProps, ThemeToggle, type ThemeToggleProps, type ToggleVariant, buildConfig, cx, defaultColors, defaultTheme, flatten, getConfig, kb, parseClass, parseClasses, resolve, styled, updateConfig, useColors, useGlobalDarkMode, useIsDark, useResolvedStyle, useStyles, useTheme, wrapColors };

package/dist/index.d.ts

@@ -139,6 +139,25 @@ interface ThemeContextValue {
 }
 declare const ThemeContext: React.Context<ThemeContextValue | null>;
 declare function useTheme(): ThemeContextValue;
+declare function useIsDark(): boolean;
+
+interface ColorScale {
+    /** `colors.blue[6]` → raw hex string */
+    readonly [shade: number]: string;
+    /** `colors.blue['6/50']` → shade 6 at 50% opacity */
+    readonly [key: string]: string;
+}
+interface ColorsAPI {
+    /** Named color scale (e.g. `colors.blue`) or flat value (e.g. `colors.white`) */
+    readonly [color: string]: string | ColorScale | ColorsAPI['alpha'];
+    /** Flat color with opacity shorthand: `colors['white/50']` */
+    /** Apply opacity to any CSS color string.
+     *  `colors.alpha('#3b82f6', 50)` → `'rgba(59,130,246,0.5)'`
+     *  `colors.alpha('rgb(0,0,0)', 10)` → `'rgba(0,0,0,0.1)'` */
+    alpha(color: string, opacity: number): string;
+}
+declare function wrapColors(rawColors: ThemeColors): ColorsAPI;
+declare function useColors(): ColorsAPI;
 
 interface ThemeProviderProps {
     children: ReactNode;
@@ -249,7 +268,7 @@ declare function useResolvedStyle(classString: string | string[]): ResolvedStyle
 
 /**
  * Subscribe to the global dark-mode store with React's concurrent-safe
- * useSyncExternalStore so that any component using className/tw re-renders
+ * useSyncExternalStore so that any component using className/kb re-renders
  * immediately when the theme changes — without needing ThemeContext.
  */
 declare function useGlobalDarkMode(): boolean;
@@ -272,7 +291,7 @@ interface InteractiveWrapperProps {
     onBlur?: (...args: any[]) => void;
 }
 /**
- * Thin wrapper rendered automatically by the JSX runtime whenever a className/tw
+ * Thin wrapper rendered automatically by the JSX runtime whenever a className/kb
  * string contains interactive modifiers (hover:, pressed:, focus:, active:, …).
  *
  * Manages interaction state locally and flattens the correct style bucket on
@@ -291,20 +310,20 @@ declare const InteractiveWrapper: React__default.ForwardRefExoticComponent<Inter
  *
  * ```ts
  * // Inside a component use useStyles() instead.
- * // tw() is useful for StyleSheet.create() calls and static values.
+ * // kb() is useful for StyleSheet.create() calls and static values.
  *
  * const styles = StyleSheet.create({
- *   container: tw('flex-1 bg-white p-4') as any,
+ *   container: kb('flex-1 bg-white p-4') as any,
  * });
  *
  * // Web: use as className
- * <div className={tw('bg-white dark:bg-gray-900 p-4') as string} />
+ * <div className={kb('bg-white dark:bg-gray-900 p-4') as string} />
  * ```
  *
  * @param classString   Space-separated utility classes
  * @param isDark        Whether dark mode is active (default: false)
  */
-declare function tw(classString: string, isDark?: boolean): StyleValue | string;
+declare function kb(classString: string, isDark?: boolean): StyleValue | string;
 /**
  * Conditionally join class names. Falsy values are ignored.
  *
@@ -315,4 +334,4 @@ declare function tw(classString: string, isDark?: boolean): StyleValue | string;
  */
 declare function cx(...classes: Array<string | false | null | undefined>): string;
 
-export { type FrameworkConfig, type InteractionState, InteractiveWrapper, type InteractiveWrapperProps, type ParsedClass, type PluginAPI, type ResolvedConfig, type ResolvedStyle, type StyleValue, type StyledProps, type ThemeConfig, ThemeContext, type ThemeContextValue, type ThemeMode, ThemeProvider, type ThemeProviderProps, ThemeToggle, type ThemeToggleProps, type ToggleVariant, buildConfig, cx, defaultColors, defaultTheme, flatten, getConfig, parseClass, parseClasses, resolve, styled, tw, updateConfig, useGlobalDarkMode, useResolvedStyle, useStyles, useTheme };
+export { type ColorScale, type ColorsAPI, type FrameworkConfig, type InteractionState, InteractiveWrapper, type InteractiveWrapperProps, type ParsedClass, type PluginAPI, type ResolvedConfig, type ResolvedStyle, type StyleValue, type StyledProps, type ThemeConfig, ThemeContext, type ThemeContextValue, type ThemeMode, ThemeProvider, type ThemeProviderProps, ThemeToggle, type ThemeToggleProps, type ToggleVariant, buildConfig, cx, defaultColors, defaultTheme, flatten, getConfig, kb, parseClass, parseClasses, resolve, styled, updateConfig, useColors, useGlobalDarkMode, useIsDark, useResolvedStyle, useStyles, useTheme, wrapColors };