@metadiv-studio/context

A lightweight utility package for creating React contexts with enhanced state management capabilities. This package provides a simplified way to create and manage React contexts with built-in state management utilities.

Installation

npm install @metadiv-studio/context

Features

• Simplified Context Creation: Create React contexts with less boilerplate code
• State Management Integration: Built-in state management utilities for context values
• Provider Composition: Easy composition of multiple providers
• TypeScript Support: Full TypeScript support with proper type inference
• React 18 Compatible: Built for modern React applications

API Reference

createContext<T>()

Creates a React context and returns a tuple containing:

• A custom hook to consume the context
• The context provider component

Type Parameters:

• T: The type of the context value

Returns:

• [useContext, Provider]: A tuple containing the hook and provider

withProviders(providers: IProvider[])

A higher-order component utility that allows you to wrap a component with multiple providers in a clean, readable way.

Parameters:

• providers: An array of provider components

Returns:

• A function that takes a component and returns it wrapped with all the providers

Usage Guide

Basic Context Creation

import { createContext } from "@metadiv-studio/context";
import { useState } from "react";

// Define your context interface
interface IThemeContext {
  theme: string;
  setTheme: (theme: string) => void;
}

// Create the context
const [useThemeContext, ThemeProvider] = createContext<IThemeContext>();

// Create your provider component
export const ThemeContextProvider = ({ children }: { children: React.ReactNode }) => {
  const [theme, setTheme] = useState("light");

  return (
    <ThemeProvider value={{ theme, setTheme }}>
      {children}
    </ThemeProvider>
  );
};

// Export the hook for consumers
export { useThemeContext };

Using the Context

import { useThemeContext } from "./ThemeContext";

const ThemeToggle = () => {
  const { theme, setTheme } = useThemeContext();
  
  return (
    <button onClick={() => setTheme(theme === "light" ? "dark" : "light")}>
      Current theme: {theme}
    </button>
  );
};

Advanced Example: Locale Context

Here's a more complex example showing how to create a locale context with localStorage persistence and routing:

import { createContext } from "@metadiv-studio/context";
import { useState, useEffect } from "react";
import { useRouter } from "next/router";

// Define your data class for state management
class LocaleData {
  locale = useState<"en" | "fr" | "es">("en");
}

// Define your context interface
interface ILocaleContext {
  data: LocaleData;
  setLocale: (locale: "en" | "fr" | "es") => void;
  getLocale: () => "en" | "fr" | "es";
}

// Create the context
const [useLocaleContext, LocaleProvider] = createContext<ILocaleContext>();

// Create your provider component
export const LocaleContextProvider = ({ children }: { children: React.ReactNode }) => {
  const data = new LocaleData();
  const router = useRouter();

  const setLocale = (locale: "en" | "fr" | "es") => {
    data.locale.set(locale);
    localStorage.setItem("locale", locale);
    router.push(router.asPath, router.asPath, { locale });
  };

  const getLocale = () => {
    return data.locale.value;
  };

  useEffect(() => {
    const savedLocale = localStorage.getItem("locale") as "en" | "fr" | "es";
    if (savedLocale && savedLocale !== "undefined") {
      setLocale(savedLocale);
    } else {
      setLocale("en");
    }
  }, []);

  return (
    <LocaleProvider value={{ data, setLocale, getLocale }}>
      {children}
    </LocaleProvider>
  );
};

// Export the hook for consumers
export { useLocaleContext };

Provider Composition

Use the withProviders utility to compose multiple providers:

import { withProviders } from "@metadiv-studio/context";
import { ThemeContextProvider } from "./ThemeContext";
import { LocaleContextProvider } from "./LocaleContext";

const App = () => {
  return <div>Your app content</div>;
};

// Compose multiple providers
const AppWithProviders = withProviders([
  ThemeContextProvider,
  LocaleContextProvider,
])(App);

export default AppWithProviders;

State Management

The package includes a custom state management system that integrates seamlessly with React contexts. The useState function from this package provides:

• Reactive Updates: Automatic re-renders when state changes
• Type Safety: Full TypeScript support
• Context Integration: Designed to work perfectly with the context system

Requirements

• React 18 or higher
• TypeScript (recommended)

License

UNLICENSED - See package.json for details.

Contributing

This package is part of the Metadiv Studio ecosystem. For contributions, please refer to the project's contribution guidelines.