@vxrn/color-scheme 1.13.3 → 1.13.4

package/src/userScheme.ts

@@ -19,6 +19,54 @@ type SchemeListener = (setting: SchemeSetting, value: Scheme) => void
 const listeners = new Set<SchemeListener>()
 const storageKey = 'vxrn-scheme'
 
+// force scheme: when set, locks the scheme and ignores user/system preferences
+let _forceScheme: Scheme | null = null
+
+function notifyListeners() {
+  listeners.forEach((listener) => {
+    listener(currentSetting, currentValue)
+  })
+}
+
+function restoreUnforcedScheme() {
+  if (typeof localStorage !== 'undefined') {
+    const stored = localStorage.getItem(storageKey) as SchemeSetting | null
+    if (stored) {
+      currentSetting = stored
+      currentValue = stored === 'system' ? resolveValue('system') : stored
+      return
+    }
+  }
+
+  currentSetting = 'system'
+  currentValue = resolveValue('system')
+}
+
+/**
+ * Lock the color scheme to a fixed value. When set, user preferences and system
+ * changes are ignored, and `setUserScheme` becomes a no-op.
+ * Pass `null` to clear the force and restore normal behavior.
+ */
+export function setForceScheme(scheme: Scheme | null) {
+  const wasForced = _forceScheme
+
+  if (wasForced === scheme) return
+
+  _forceScheme = scheme
+
+  if (scheme) {
+    currentSetting = scheme
+    currentValue = scheme
+  } else if (wasForced) {
+    restoreUnforcedScheme()
+    startWebListener()
+  }
+}
+
+export function getForceScheme(): Scheme | null {
+  return _forceScheme
+}
+
 // eagerly init from localStorage on module load (native only - web uses effect for SSR)
 function getInitialSetting(): SchemeSetting {
   if (process.env.TAMAGUI_TARGET === 'native') {
@@ -89,17 +137,17 @@ function resolveValue(setting: SchemeSetting): Scheme {
 
 // Only update the resolved value when system theme changes (don't change setting)
 function updateValueFromSystem() {
+  if (_forceScheme) return
   const value = resolveValue('system')
   if (value !== currentValue) {
     currentValue = value
     // don't call Appearance.setColorScheme when following system - it breaks the listener
-    listeners.forEach((l) => {
-      l(currentSetting, currentValue)
-    })
+    notifyListeners()
   }
 }
 
 function updateScheme(setting: SchemeSetting) {
+  if (_forceScheme) return
   const value = setting === 'system' ? resolveValue('system') : setting
 
   if (value !== currentValue || currentSetting !== setting) {
@@ -117,9 +165,7 @@ function updateScheme(setting: SchemeSetting) {
       }
     }
 
-    listeners.forEach((l) => {
-      l(currentSetting, currentValue)
-    })
+    notifyListeners()
   }
 }
 
@@ -130,6 +176,7 @@ function updateScheme(setting: SchemeSetting) {
  * @param setting - 'system', 'light', or 'dark'
  */
 export function setUserScheme(setting: SchemeSetting) {
+  if (_forceScheme) return
   if (typeof localStorage !== 'undefined') {
     localStorage.setItem(storageKey, setting)
   }
@@ -142,6 +189,7 @@ export function setUserScheme(setting: SchemeSetting) {
  * @returns Object with setting and resolved value
  */
 export function getUserScheme(): { setting: SchemeSetting; value: Scheme } {
+  if (_forceScheme) return { setting: _forceScheme, value: _forceScheme }
   return { setting: currentSetting, value: currentValue }
 }
 
@@ -174,31 +222,38 @@ export function onUserSchemeChange(listener: SchemeListener) {
  */
 export function useUserScheme(): UserScheme {
   const [state, setState] = useState(() => getUserScheme())
+  const snapshot = getUserScheme()
+  const resolvedState =
+    state.setting === snapshot.setting && state.value === snapshot.value
+      ? state
+      : snapshot
 
   useIsomorphicLayoutEffect(() => {
-    // restore from localStorage on mount
-    if (typeof localStorage !== 'undefined') {
-      const stored = localStorage.getItem(storageKey) as SchemeSetting | null
-      if (stored) {
-        updateScheme(stored)
+    if (!_forceScheme) {
+      // restore from localStorage on mount
+      if (typeof localStorage !== 'undefined') {
+        const stored = localStorage.getItem(storageKey) as SchemeSetting | null
+        if (stored) {
+          updateScheme(stored)
+        }
       }
+      startWebListener()
     }
 
+    // always subscribe so force→unforce transitions propagate via setForceScheme(null)
     const dispose = onUserSchemeChange((setting, value) => {
       setState({ setting, value })
     })
 
-    startWebListener()
-
     return dispose
   }, [])
 
   return useMemo(
     () => ({
-      setting: state.setting,
-      value: state.value,
+      setting: resolvedState.setting,
+      value: resolvedState.value,
       set: setUserScheme,
     }),
-    [state.setting, state.value]
+    [resolvedState.setting, resolvedState.value]
   )
 }

package/types/index.d.ts

@@ -3,11 +3,13 @@ export type { Scheme } from './systemScheme';
 export type { SchemeSetting, UserScheme } from './userScheme';
 export { getSystemScheme, useSystemScheme } from './systemScheme';
 export { getUserScheme, onUserSchemeChange, setUserScheme, useUserScheme, } from './userScheme';
-export declare function SchemeProvider({ children, getClassName, defaultScheme, }: {
+export declare function SchemeProvider({ children, getClassName, defaultScheme, forceScheme, }: {
     children: any;
     getClassName?: (name: Scheme) => string;
     /** Force a default scheme when no user preference is stored. Without this, falls back to system preference. */
     defaultScheme?: Scheme;
+    /** Lock the scheme to this value. Ignores user preference, system preference, and localStorage. Prevents hydration flicker. */
+    forceScheme?: Scheme;
 }): import("react/jsx-runtime").JSX.Element;
 export declare function MetaTheme({ color, darkColor, lightColor, }: {
     color?: string;

package/types/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAA;AAI5C,YAAY,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAA;AAC5C,YAAY,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AAG7D,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAA;AACjE,OAAO,EACL,aAAa,EACb,kBAAkB,EAClB,aAAa,EACb,aAAa,GACd,MAAM,cAAc,CAAA;AAIrB,wBAAgB,cAAc,CAAC,EAC7B,QAAQ,EACR,YAAoC,EACpC,aAAa,GACd,EAAE;IACD,QAAQ,EAAE,GAAG,CAAA;IACb,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAA;IACvC,+GAA+G;IAC/G,aAAa,CAAC,EAAE,MAAM,CAAA;CACvB,2CAsDA;AAED,wBAAgB,SAAS,CAAC,EACxB,KAAK,EACL,SAAS,EACT,UAAU,GACX,EAAE;IACD,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,SAAS,EAAE,MAAM,CAAA;IACjB,UAAU,EAAE,MAAM,CAAA;CACnB,2CAyBA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAA;AAS5C,YAAY,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAA;AAC5C,YAAY,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AAG7D,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAA;AACjE,OAAO,EACL,aAAa,EACb,kBAAkB,EAClB,aAAa,EACb,aAAa,GACd,MAAM,cAAc,CAAA;AAIrB,wBAAgB,cAAc,CAAC,EAC7B,QAAQ,EACR,YAAoC,EACpC,aAAa,EACb,WAAW,GACZ,EAAE;IACD,QAAQ,EAAE,GAAG,CAAA;IACb,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAA;IACvC,+GAA+G;IAC/G,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,+HAA+H;IAC/H,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB,2CAmEA;AAED,wBAAgB,SAAS,CAAC,EACxB,KAAK,EACL,SAAS,EACT,UAAU,GACX,EAAE;IACD,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,SAAS,EAAE,MAAM,CAAA;IACjB,UAAU,EAAE,MAAM,CAAA;CACnB,2CA0BA"}

package/types/userScheme.d.ts

@@ -9,6 +9,13 @@ export type UserScheme = {
     set: (setting: SchemeSetting) => void;
 };
 type SchemeListener = (setting: SchemeSetting, value: Scheme) => void;
+/**
+ * Lock the color scheme to a fixed value. When set, user preferences and system
+ * changes are ignored, and `setUserScheme` becomes a no-op.
+ * Pass `null` to clear the force and restore normal behavior.
+ */
+export declare function setForceScheme(scheme: Scheme | null): void;
+export declare function getForceScheme(): Scheme | null;
 /**
  * Imperatively set the user's color scheme preference.
  * Persists to localStorage and updates all listeners.

package/types/userScheme.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"userScheme.d.ts","sourceRoot":"","sources":["../src/userScheme.ts"],"names":[],"mappings":"AAGA,OAAO,EAAmB,KAAK,MAAM,EAAE,MAAM,gBAAgB,CAAA;AAE7D,MAAM,MAAM,aAAa,GAAG,QAAQ,GAAG,OAAO,GAAG,MAAM,CAAA;AAEvD,MAAM,MAAM,UAAU,GAAG;IACvB,0DAA0D;IAC1D,OAAO,EAAE,aAAa,CAAA;IACtB,6CAA6C;IAC7C,KAAK,EAAE,MAAM,CAAA;IACb,gCAAgC;IAChC,GAAG,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,IAAI,CAAA;CACtC,CAAA;AAED,KAAK,cAAc,GAAG,CAAC,OAAO,EAAE,aAAa,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAA;AA6GrE;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,aAAa,QAKnD;AAED;;;;GAIG;AACH,wBAAgB,aAAa,IAAI;IAAE,OAAO,EAAE,aAAa,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAEzE;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,cAAc,cAM1D;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,IAAI,UAAU,CA6B1C"}
+{"version":3,"file":"userScheme.d.ts","sourceRoot":"","sources":["../src/userScheme.ts"],"names":[],"mappings":"AAGA,OAAO,EAAmB,KAAK,MAAM,EAAE,MAAM,gBAAgB,CAAA;AAE7D,MAAM,MAAM,aAAa,GAAG,QAAQ,GAAG,OAAO,GAAG,MAAM,CAAA;AAEvD,MAAM,MAAM,UAAU,GAAG;IACvB,0DAA0D;IAC1D,OAAO,EAAE,aAAa,CAAA;IACtB,6CAA6C;IAC7C,KAAK,EAAE,MAAM,CAAA;IACb,gCAAgC;IAChC,GAAG,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,IAAI,CAAA;CACtC,CAAA;AAED,KAAK,cAAc,GAAG,CAAC,OAAO,EAAE,aAAa,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAA;AA4BrE;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,QAcnD;AAED,wBAAgB,cAAc,IAAI,MAAM,GAAG,IAAI,CAE9C;AAwGD;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,aAAa,QAMnD;AAED;;;;GAIG;AACH,wBAAgB,aAAa,IAAI;IAAE,OAAO,EAAE,aAAa,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAGzE;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,cAAc,cAM1D;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,IAAI,UAAU,CAoC1C"}