@kbach/ui 0.1.0-beta.0 → 0.1.0-beta.1

package/dist/core/index.d.ts

@@ -188,6 +188,43 @@ interface ResolvedConfig {
     plugins: Array<(api: PluginAPI) => void>;
 }
 
+/**
+ * Returns a value that's the SAME object across every physical copy of core/
+ * a bundler might produce for a single running process — not just across
+ * dist/index.js / dist/jsx-runtime.js / dist/jsx-dev-runtime.js (the CJS
+ * build, which already shares one real dist/core/index.js via
+ * externalization — see tsup.config.ts's CORE_EXTERNAL), but ALSO across
+ * that CJS build and the separate ESM build (dist/index.mjs etc., which
+ * inlines its own copy of core/ — a deliberate, accepted trade-off for
+ * Rollup/Vite compatibility, see context.tsx's ThemeContext comment for the
+ * full story).
+ *
+ * Confirmed as a real, live bug (not just theoretical), back when ThemeProvider
+ * still had a separate native-specific wrapper at the now-removed
+ * '@kbach/ui/native' subpath (see native/index.ts): a React Native app that
+ * reached @kbach/ui through more than one physical dist file — e.g.
+ * `import { ThemeProvider } from '@kbach/ui/native'` in one file and
+ * `import { useIsDark } from '@kbach/ui'` in another, which Metro can resolve
+ * to DIFFERENT dist files per call site — got dark:/light: classes silently
+ * inert from one instance while useIsDark() read a different,
+ * correctly-updating instance (or vice versa), depending on which module
+ * each half of the app happened to load through. ThemeProvider now auto-
+ * detects native itself (no separate wrapper/import path to diverge on), but
+ * the underlying dual-build split (ESM for Rollup/Vite, CJS for Metro) is
+ * still real, so darkModeStore/responsiveStore/config/etc. still need this —
+ * jsx-runtime.tsx, for instance, still reaches core/ as its own call site.
+ * See RULES.md rule 3: this is exactly the "globalThis-singleton hack" it
+ * allows when a real fix (one guaranteed physical module) isn't available —
+ * which it isn't here, short of giving up either Rollup or Metro compatibility
+ * entirely.
+ *
+ * Keyed on Symbol.for() (the well-known global symbol registry, shared
+ * across realms/module copies by spec) rather than a plain string property,
+ * so this can never collide with anything else that happens to touch
+ * globalThis.
+ */
+declare function getGlobalSingleton<T>(key: string, create: () => T): T;
+
 /**
  * True for a mode-aware color pair (`{ light, dark }`), as opposed to a plain
  * hex/rgb/alias string. Shared by config.ts (alias-chain resolution),
@@ -1271,14 +1308,17 @@ declare function initConfig(userConfig: FrameworkConfig): void;
  * synchronously during render without needing context. ThemeProvider writes to it;
  * DarkWrapper / InteractiveWrapper subscribe via useSyncExternalStore.
  *
- * Used to be backed by globalThis instead of a plain module-level variable:
- * tsup used to bundle core/ separately into each of dist/index.js and
- * dist/jsx-runtime.js (esbuild doesn't support code-splitting CJS output),
- * so Metro loading each by path got independent copies of this module with
- * independent top-level state. core/ is now built as its own dist/core/
- * entry and required externally by both (see packages/ui/tsup.config.ts),
- * so there's only ever one real instance of this module to begin with — a
- * plain module-level object is enough.
+ * Backed by getGlobalSingleton() (globalThis-keyed), not a plain module-level
+ * variable — core/ being built as its own shared dist/core/ entry (see
+ * tsup.config.ts's CORE_EXTERNAL) only guarantees one instance across the CJS
+ * build (dist/index.js, dist/jsx-runtime.js, dist/jsx-dev-runtime.js). The
+ * separate ESM build (dist/index.mjs etc., required for Rollup/Vite — see
+ * context.tsx's ThemeContext comment) inlines its own copy, and Metro can
+ * route different call sites in the same app through either one. Confirmed
+ * as a real bug this way: dark:/light: classes went completely inert (while
+ * useIsDark() kept reading correctly) in an app mixing
+ * `import ... from '@kbach/ui/native'` and `import ... from '@kbach/ui'`
+ * — the two ended up on different physical copies of this store.
  */
 /**
  * Silently update isDark without notifying subscribers.
@@ -1308,13 +1348,12 @@ declare function subscribeGlobalDarkMode(callback: () => void): () => void;
 /**
  * Global responsive width store.
  *
- * Used to be backed by globalThis so all CJS bundle splits (index.js,
- * jsx-runtime.js, jsx-dev-runtime.js) shared one instance — tsup used to
- * bundle core/ separately into each of them (esbuild doesn't support
- * code-splitting CJS output). core/ is now built as its own dist/core/
- * entry and required externally by all three (see
- * packages/ui/tsup.config.ts), so there's only ever one real instance of
- * this module to begin with — a plain module-level object is enough.
+ * Backed by getGlobalSingleton() (globalThis-keyed) — see
+ * darkModeStore.ts's header comment for why a plain module-level object
+ * isn't enough: core/ being its own shared dist/core/ entry only covers the
+ * CJS build (dist/index.js, dist/jsx-runtime.js, dist/jsx-dev-runtime.js);
+ * the separate ESM build inlines its own copy, and Metro can route
+ * different call sites in the same app through either one.
  */
 type WidthListener = () => void;
 /** Synchronous write for use in the render phase. */
@@ -1343,4 +1382,4 @@ declare function subscribeGlobalWidth(listener: WidthListener): () => void;
  */
 declare function getActiveBreakpoints(width?: number, screens?: Record<string, number>): Set<string>;
 
-export { BASE_RESET, type ColorShades, type ColorValue, type DarkMode, type DefaultColorName, type DefaultSpacingKey, type FrameworkConfig, LRUCache, type ParsedClass, type Platform, type PluginAPI, RESET_STYLE_ID, type ResolvedConfig, type ResolvedStyle, type StyleValue, type ThemeColors, type ThemeConfig, type ThemeMode, type ThemeSpacing, buildConfig, clearCache, clearPluginModifiers, defaultColors, defaultTheme, disableRuntimeCSS, escapeCSSSelector, expandModeAwareColorClasses, flatten, generateClassCSS, generateKbachTypesDts, getActiveBreakpoints, getAllModifierNames, getBuiltinStandaloneNames, getBuiltinUtilityPrefixes, getConfig, getDefaultFontFamily, getEffectiveIsWeb, getGlobalDarkMode, getGlobalScreens, getGlobalWidth, getInteractiveModifiers, getModeModifiers, getModifier, getResponsiveModifiers, initConfig, isKnownModifier, isKnownUtility, isModeAwareColor, isNative, isRuntimeCSSDisabled, isWeb, kbachWarn, matchModifier, normalizeClassString, onConfigChange, parseClass, parseClasses, parseHexRgb, registerModifier, resetConfig, resolve, resolveColor, resolveSizing, resolveSpacing, resolveUtility, setDefaultFontFamily, setGlobalDarkMode, setGlobalWidth, setResolveTarget, splitClassTokens, subscribeGlobalDarkMode, subscribeGlobalWidth, syncGlobalDarkMode, syncGlobalScreens, syncGlobalWidth, toNativeValue, updateConfig };
+export { BASE_RESET, type ColorShades, type ColorValue, type DarkMode, type DefaultColorName, type DefaultSpacingKey, type FrameworkConfig, LRUCache, type ParsedClass, type Platform, type PluginAPI, RESET_STYLE_ID, type ResolvedConfig, type ResolvedStyle, type StyleValue, type ThemeColors, type ThemeConfig, type ThemeMode, type ThemeSpacing, buildConfig, clearCache, clearPluginModifiers, defaultColors, defaultTheme, disableRuntimeCSS, escapeCSSSelector, expandModeAwareColorClasses, flatten, generateClassCSS, generateKbachTypesDts, getActiveBreakpoints, getAllModifierNames, getBuiltinStandaloneNames, getBuiltinUtilityPrefixes, getConfig, getDefaultFontFamily, getEffectiveIsWeb, getGlobalDarkMode, getGlobalScreens, getGlobalSingleton, getGlobalWidth, getInteractiveModifiers, getModeModifiers, getModifier, getResponsiveModifiers, initConfig, isKnownModifier, isKnownUtility, isModeAwareColor, isNative, isRuntimeCSSDisabled, isWeb, kbachWarn, matchModifier, normalizeClassString, onConfigChange, parseClass, parseClasses, parseHexRgb, registerModifier, resetConfig, resolve, resolveColor, resolveSizing, resolveSpacing, resolveUtility, setDefaultFontFamily, setGlobalDarkMode, setGlobalWidth, setResolveTarget, splitClassTokens, subscribeGlobalDarkMode, subscribeGlobalWidth, syncGlobalDarkMode, syncGlobalScreens, syncGlobalWidth, toNativeValue, updateConfig };

package/dist/core/index.js

@@ -43,6 +43,7 @@ __export(index_exports, {
   getEffectiveIsWeb: () => getEffectiveIsWeb,
   getGlobalDarkMode: () => getGlobalDarkMode,
   getGlobalScreens: () => getGlobalScreens,
+  getGlobalSingleton: () => getGlobalSingleton,
   getGlobalWidth: () => getGlobalWidth,
   getInteractiveModifiers: () => getInteractiveModifiers,
   getModeModifiers: () => getModeModifiers,
@@ -84,6 +85,18 @@ __export(index_exports, {
 });
 module.exports = __toCommonJS(index_exports);
 
+// src/core/globalSingleton.ts
+function getGlobalSingleton(key, create) {
+  const symbolKey = /* @__PURE__ */ Symbol.for(`__kbach_${key}__`);
+  const g = globalThis;
+  let value = g[symbolKey];
+  if (value === void 0) {
+    value = create();
+    g[symbolKey] = value;
+  }
+  return value;
+}
+
 // src/core/colorValue.ts
 function isModeAwareColor(v) {
   return typeof v === "object" && v !== null && "light" in v && "dark" in v;
@@ -2989,7 +3002,12 @@ var BASE_RESET = [
 ].join("\n");
 
 // src/core/responsiveStore.ts
-var store = { width: 0, notifiedWidth: 0, screens: {}, listeners: /* @__PURE__ */ new Set() };
+var store = getGlobalSingleton("responsiveStore", () => ({
+  width: 0,
+  notifiedWidth: 0,
+  screens: {},
+  listeners: /* @__PURE__ */ new Set()
+}));
 function syncGlobalWidth(width) {
   store.width = width;
 }
@@ -3047,12 +3065,12 @@ function getSortedEntries(resolved) {
   }
   return sorted;
 }
-var _defaultFontFamily;
+var _fontFamilyHolder = getGlobalSingleton("defaultFontFamily", () => ({ value: void 0 }));
 function setDefaultFontFamily(font) {
-  _defaultFontFamily = font;
+  _fontFamilyHolder.value = font;
 }
 function getDefaultFontFamily() {
-  return _defaultFontFamily;
+  return _fontFamilyHolder.value;
 }
 var _styleEl = null;
 var _ruleIndexByKey = /* @__PURE__ */ new Map();
@@ -3085,12 +3103,12 @@ function evictInjectedRule(rule) {
   }
 }
 var _injectedRules = new LRUCache(5e4, evictInjectedRule);
-var _runtimeCSSDisabled = false;
+var _runtimeCSSHolder = getGlobalSingleton("runtimeCSSDisabled", () => ({ value: false }));
 function disableRuntimeCSS() {
-  _runtimeCSSDisabled = true;
+  _runtimeCSSHolder.value = true;
 }
 function isRuntimeCSSDisabled() {
-  return _runtimeCSSDisabled;
+  return _runtimeCSSHolder.value;
 }
 function getStyleEl() {
   if (_styleEl) return _styleEl;
@@ -3460,7 +3478,10 @@ function deepMerge(base, override) {
   }
   return result;
 }
-var configStore = { resolved: null, listeners: /* @__PURE__ */ new Set() };
+var configStore = getGlobalSingleton("configStore", () => ({
+  resolved: null,
+  listeners: /* @__PURE__ */ new Set()
+}));
 function getConfig() {
   if (configStore.resolved) return configStore.resolved;
   configStore.resolved = buildConfig({});
@@ -3629,7 +3650,11 @@ function initConfig(userConfig) {
 }
 
 // src/core/darkModeStore.ts
-var store2 = { isDark: false, notifiedIsDark: false, subscribers: /* @__PURE__ */ new Set() };
+var store2 = getGlobalSingleton("darkModeStore", () => ({
+  isDark: false,
+  notifiedIsDark: false,
+  subscribers: /* @__PURE__ */ new Set()
+}));
 function syncGlobalDarkMode(isDark) {
   store2.isDark = isDark;
 }
@@ -3671,6 +3696,7 @@ function subscribeGlobalDarkMode(callback) {
   getEffectiveIsWeb,
   getGlobalDarkMode,
   getGlobalScreens,
+  getGlobalSingleton,
   getGlobalWidth,
   getInteractiveModifiers,
   getModeModifiers,

package/dist/index.d.ts

@@ -19,9 +19,6 @@ interface ThemeContextValue {
     /** The fully resolved framework config (theme values, darkMode strategy, etc.) */
     config: ResolvedConfig;
 }
-declare global {
-    var __kbachThemeContext: Context<ThemeContextValue | null> | undefined;
-}
 declare const ThemeContext: Context<ThemeContextValue | null>;
 declare function useTheme(): ThemeContextValue;
 declare function useIsDark(): boolean;
@@ -136,22 +133,19 @@ interface ThemeProviderProps {
     /**
      * System color scheme for native `defaultMode="system"`.
      *
-     * Pass the value of `useColorScheme()` from `react-native`. When importing
-     * `ThemeProvider` from `@kbach/ui/native` this is handled automatically.
+     * On React Native this is detected automatically via `useColorScheme()` —
+     * pass this prop only to override that (e.g. in tests, or Storybook).
      *
      * @example
      * ```tsx
-     * import { useColorScheme } from 'react-native';
-     * const colorScheme = useColorScheme();
-     * <ThemeProvider defaultMode="system" colorScheme={colorScheme}>…</ThemeProvider>
+     * <ThemeProvider defaultMode="system" colorScheme="dark">…</ThemeProvider>
      * ```
      */
     colorScheme?: 'light' | 'dark' | null;
     /**
      * Current window/screen width in pixels for responsive breakpoints.
-     * On web this is read from `window.innerWidth` automatically.
-     * When importing `ThemeProvider` from `@kbach/ui/native` this is provided
-     * automatically from `useWindowDimensions()`.
+     * Detected automatically on both web (`window.innerWidth`) and React
+     * Native (`useWindowDimensions()`) — pass this prop only to override that.
      */
     windowWidth?: number;
     /** Override the config (useful for per-tree config). Defaults to global getConfig(). */