Color Mode Management

/**
 * React provider for color mode context management
 * @param props - Provider configuration options
 * @returns JSX element providing color mode context
 */
function ColorModeProvider(props: ColorModeProviderProps): JSX.Element;

interface ColorModeProviderProps {
  /**
   * Initial color mode value
   */
  value?: "light" | "dark";
  /**
   * React children to receive color mode context
   */
  children?: React.ReactNode;
  /**
   * Color mode configuration options
   */
  options?: {
    /**
     * Whether to use system color mode preference
     * @default true
     */
    useSystemColorMode?: boolean;
    /**
     * Initial color mode when no stored value exists
     * @default "light"
     */
    initialColorMode?: "light" | "dark";
    /**
     * Disable CSS transitions when switching modes
     * @default false
     */
    disableTransition?: boolean;
  };
}

import { ColorModeProvider, ChakraProvider } from "@chakra-ui/system";

function App() {
  return (
    <ColorModeProvider
      options={{
        initialColorMode: "dark",
        useSystemColorMode: true
      }}
    >
      <ChakraProvider theme={theme}>
        <YourApp />
      </ChakraProvider>
    </ColorModeProvider>
  );
}

/**
 * Hook for accessing color mode state and controls
 * @returns Object with current mode and control functions
 */
function useColorMode(): {
  /**
   * Current color mode ("light" or "dark")
   */
  colorMode: "light" | "dark";
  /**
   * Toggle between light and dark modes
   */
  toggleColorMode: () => void;
  /**
   * Set specific color mode
   */
  setColorMode: (value: "light" | "dark") => void;
};

import { useColorMode } from "@chakra-ui/system";

function ColorModeToggle() {
  const { colorMode, toggleColorMode } = useColorMode();
  
  return (
    <button onClick={toggleColorMode}>
      Switch to {colorMode === "light" ? "dark" : "light"} mode
    </button>
  );
}

function ColorModeSelector() {
  const { colorMode, setColorMode } = useColorMode();
  
  return (
    <select 
      value={colorMode} 
      onChange={(e) => setColorMode(e.target.value as "light" | "dark")}
    >
      <option value="light">Light</option>
      <option value="dark">Dark</option>
    </select>
  );
}

/**
 * Hook that returns different values based on current color mode
 * @param light - Value to return in light mode
 * @param dark - Value to return in dark mode
 * @returns Value based on current color mode
 */
function useColorModeValue<TLight, TDark>(
  light: TLight, 
  dark: TDark
): TLight | TDark;

import { useColorModeValue } from "@chakra-ui/system";

function ThemedComponent() {
  const bg = useColorModeValue("white", "gray.800");
  const color = useColorModeValue("black", "white");
  const borderColor = useColorModeValue("gray.200", "gray.600");
  
  return (
    <div style={{
      backgroundColor: bg,
      color: color,
      borderColor: borderColor,
      border: "1px solid"
    }}>
      This component adapts to color mode
    </div>
  );
}

/**
 * Component wrapper that forces dark mode rendering for its children
 * @param props - Component props
 * @returns JSX element with forced dark mode
 */
function DarkMode(props: { children: React.ReactNode }): JSX.Element;

/**
 * Component wrapper that forces light mode rendering for its children  
 * @param props - Component props
 * @returns JSX element with forced light mode
 */
function LightMode(props: { children: React.ReactNode }): JSX.Element;

import { DarkMode, LightMode } from "@chakra-ui/system";

function MixedModeExample() {
  return (
    <div>
      <div>This follows the global color mode</div>
      
      <DarkMode>
        <div>This is always in dark mode</div>
      </DarkMode>
      
      <LightMode>
        <div>This is always in light mode</div>
      </LightMode>
    </div>
  );
}

/**
 * Script component for SSR color mode initialization
 * Prevents flash of wrong color mode on page load
 * @param props - Script configuration
 * @returns JSX script element
 */
function ColorModeScript(props?: ColorModeScriptProps): JSX.Element;

interface ColorModeScriptProps {
  /**
   * Initial color mode for SSR
   * @default "light"
   */
  initialColorMode?: "light" | "dark" | "system";
  /**
   * Storage type for persistence
   * @default "localStorage"
   */
  type?: "localStorage" | "cookie";
  /**
   * Storage key name
   * @default "chakra-ui-color-mode"
   */
  storageKey?: string;
  /**
   * Nonce for CSP compliance
   */
  nonce?: string;
}

/**
 * Generate script source for color mode initialization
 * @param options - Script generation options
 * @returns Script source string
 */
function getScriptSrc(options?: {
  initialColorMode?: "light" | "dark" | "system";
  type?: "localStorage" | "cookie";
  storageKey?: string;
}): string;

import { ColorModeScript } from "@chakra-ui/system";
import Document, { Html, Head, Main, NextScript } from "next/document";

class MyDocument extends Document {
  render() {
    return (
      <Html>
        <Head>
          <ColorModeScript initialColorMode="dark" />
        </Head>
        <body>
          <Main />
          <NextScript />
        </body>
      </Html>
    );
  }
}

/**
 * Browser localStorage persistence manager
 */
declare const localStorageManager: ColorModeManager;

/**
 * Cookie-based persistence manager
 */
declare const cookieStorageManager: ColorModeManager;

/**
 * SSR-compatible cookie manager with initial cookie value
 * @param cookie - Initial cookie string from server
 * @returns Cookie storage manager
 */
function cookieStorageManagerSSR(cookie: string): ColorModeManager;

/**
 * Factory for custom localStorage manager with custom key
 * @param key - Storage key name
 * @returns Custom localStorage manager
 */
function createLocalStorageManager(key: string): ColorModeManager;

/**
 * Factory for custom cookie storage manager
 * @param key - Cookie name
 * @param cookie - Initial cookie value for SSR
 * @returns Custom cookie storage manager
 */
function createCookieStorageManager(
  key: string, 
  cookie?: string
): ColorModeManager;

interface ColorModeManager {
  type: "cookie" | "localStorage";
  get(): "light" | "dark" | undefined;
  set(value: "light" | "dark"): void;
}

import { 
  ColorModeProvider, 
  createLocalStorageManager,
  createCookieStorageManager 
} from "@chakra-ui/system";

// Custom localStorage manager
const customStorageManager = createLocalStorageManager("my-app-color-mode");

// Custom cookie manager for SSR
const customCookieManager = createCookieStorageManager(
  "my-app-theme", 
  "light" // initial value from server
);

function App({ cookies }) {
  return (
    <ColorModeProvider
      options={{
        storageManager: createCookieStorageManager("theme", cookies)
      }}
    >
      <YourApp />
    </ColorModeProvider>
  );
}

/**
 * React context for color mode state
 * Use useColorMode hook instead of consuming directly
 */
declare const ColorModeContext: React.Context<ColorModeContextType>;

interface ColorModeContextType {
  colorMode: "light" | "dark";
  toggleColorMode: () => void;
  setColorMode: (value: "light" | "dark") => void;
  forced?: boolean;
}

// Color mode types
type ColorMode = "light" | "dark";
type ColorModeWithSystem = "light" | "dark" | "system";
type ConfigColorMode = ColorMode | "system";

// Context type
interface ColorModeContextType {
  colorMode: ColorMode;
  toggleColorMode: () => void;
  setColorMode: (value: ColorMode) => void;
  forced?: boolean;
}

// Provider props
interface ColorModeProviderProps {
  value?: ColorMode;
  children?: React.ReactNode;
  options?: {
    useSystemColorMode?: boolean;
    initialColorMode?: ColorMode;
    disableTransition?: boolean;
  };
}

// Script props  
interface ColorModeScriptProps {
  initialColorMode?: ColorModeWithSystem;
  type?: "localStorage" | "cookie";
  storageKey?: string;
  nonce?: string;
}

// Storage manager interface
interface ColorModeManager {
  type: "cookie" | "localStorage";
  get(): ColorMode | undefined;
  set(value: ColorMode): void;
}