npm package: @supercat1337/color-scheme
Description: A tiny, fast, and easy-to-use color scheme and color theme management system for JavaScript applications that works with Bootstrap 5 and supports dark and light themes.
Author: Supercat
Latest version: 1.0.2

# @supercat1337/color-scheme

A tiny, fast, and easy-to-use color scheme and color theme management system for JavaScript applications that works with Bootstrap 5 and supports dark and light themes.

## Overview

This module provides a simple way to manage color schemes in your application. It allows you to determine the user's preferred color scheme, subscribe to changes in the current color scheme, and apply a color scheme to the root element of the document.

## Usage

```javascript
import {
    applyColorTheme,
    applyColorThemeToElement,
    currentSchemeStorage,
    preferredSchemeStorage,
    systemSchemeStorage,
} from "@supercat1337/color-scheme";

// You can set the color scheme directly using the applyColorTheme function.
applyColorTheme("dark");

// You can also set the color scheme on an HTML element using the applyColorThemeToElement function.
applyColorThemeToElement(
    /** @type {HTMLInputElement} */ (document.body.querySelector("h1")),
    "light"
);

// You can also listen for changes in the current color scheme using the onSchemeChange function.
const switcher = /** @type {HTMLInputElement} */ (
    document.querySelector("input")
);

// Initialize the switcher to reflect the current color scheme.
let darkmode_is_on = currentSchemeStorage.scheme === "dark";
switcher.checked = darkmode_is_on;

// Listen for changes in the current color scheme and update the switcher accordingly.
currentSchemeStorage.onSchemeChange((scheme) => {
    let darkmode_is_on = scheme === "dark";
    switcher.checked = darkmode_is_on;
});

// Listen for changes in the switcher and update the current color scheme accordingly.
switcher.addEventListener("change", () => {
    currentSchemeStorage.scheme = switcher.checked ? "dark" : "light";
});

// You can also save the user's preferred color scheme using localStorage.
// This will allow the user to switch back to their preferred color scheme after closing their browser.
preferredSchemeStorage.scheme = currentSchemeStorage.scheme;

// You can also listen for changes in the user's preferred color scheme using the onSchemeChange function.
preferredSchemeStorage.onSchemeChange((scheme) => {
    console.log(`Preferred Color Scheme: ${scheme}`);
});

// You can also get the system color scheme.
console.log(`System Color Scheme: ${systemSchemeStorage.scheme}`);

// You can also listen for changes in the system color scheme using the onSchemeChange function.
systemSchemeStorage.onSchemeChange((scheme) => {
    console.log(`System Color Scheme: ${scheme}`);
});
```

## Objects

### SystemSchemeStorage

`The SystemSchemeStorage object` manages the system color scheme, providing methods to get and subscribe to changes in the scheme.

Methods:

-   `onSchemeChange`(callback): Subscribes to changes in the system color scheme and calls the provided callback function when the scheme changes. Returns an -unsubscribe function to stop receiving updates.
-   get `scheme`: Returns the current system color scheme, which can be either "dark" or "light".

### PreferredSchemeStorage

`The PreferredSchemeStorage object` manages the user's preferred color scheme, storing it in local storage and providing methods to get, set, and subscribe to changes in the scheme.

Methods:

-   get `scheme`: Returns the current preferred color scheme.
-   set `scheme`: Sets the preferred color scheme to a new value, updating local storage and emitting an event if the scheme changes.
-   `onSchemeChange`: Subscribes to changes in the preferred color scheme, calling the provided callback function when the scheme changes, and returns an unsubscribe function.

### CurrentSchemeStorage

`The CurrentSchemeStorage object` manages the current color scheme, storing it in local storage and providing methods to get, set, and subscribe to changes in the scheme.

Properties:

-   `darkThemeName`: The name of the dark theme.
-   `lightThemeName`: The name of the light theme.

Methods:

-   get `scheme`: Returns the current color scheme.
-   set `scheme`: Sets the current color scheme to a new value, updating local storage and emitting an event if the scheme changes.
-   `onSchemeChange`: Subscribes to changes in the current color scheme, calling the provided callback function when the scheme changes, and returns an unsubscribe function.
-   `getDefaultTheme`: Returns the default theme name based on the current color scheme.

## Functions

### applyColorTheme(theme)

Applies a color scheme to the root element of the document. The theme is used to set the `data-bs-theme` attribute, which is used by Bootstrap 5 to determine the theme to use for styled components.

-   `theme`: The color scheme to apply to the root element. Can be `"dark"`, `"light"`, `"auto"`, or a custom theme.

### applyColorThemeToElement(element, theme)

Applies a color scheme to an HTML element. The theme is used to set the `data-bs-theme` attribute on the root element of the document, which is used by Bootstrap 5 to determine the theme to use for styled components.

-   `element`: The HTML element to apply the color scheme to.
-   `theme`: The color scheme to apply to the element. Can be `"dark"`, `"light"`, `"auto"`, or a custom theme.

## License

This module is licensed under the MIT License.

## Author

Supercat1337