@cerberus-design/react 0.0.0-next-bd980a6d9bd07d60e8d7200bd4d56624754e936c

package/dist/context/theme.d.cts

@@ -0,0 +1,53 @@
+import { PropsWithChildren } from 'react';
+import { UseThemeOptions } from '../hooks/useTheme';
+/**
+ * This module provides a context and hook for the theme.
+ * @module Theme
+ */
+export type DefaultThemes = 'cerberus' | 'acheron' | 'elysium';
+export type CustomThemes<K extends string = DefaultThemes> = 'cerberus' | K;
+export type ColorModes = 'light' | 'dark' | 'system';
+export interface ThemeContextValue<T extends string = DefaultThemes> {
+    /**
+     * The current theme.
+     */
+    theme: CustomThemes<T>;
+    /**
+     * The current color mode.
+     */
+    mode: ColorModes;
+    /**
+     * Called when the theme is updated.
+     */
+    updateTheme: (theme: T) => void;
+    /**
+     * Called when the color mode is updated.
+     */
+    updateMode: (mode: ColorModes) => void;
+}
+export interface ThemeProviderProps extends UseThemeOptions {
+    /**
+     * The default theme.
+     */
+    defaultTheme?: DefaultThemes;
+    /**
+     * The default color mode.
+     */
+    defaultColorMode?: ColorModes;
+}
+/**
+ * A context provider that allows the user to set the theme and mode of the
+ * application.
+ * @see https://cerberus.digitalu.design/react/use-theme-context
+ * @example
+ * ```tsx
+ * <ThemeProvider>
+ *  <App />
+ * </ThemeProvider>
+ * ```
+ */
+export declare function ThemeProvider(props: PropsWithChildren<ThemeProviderProps>): import("react").JSX.Element;
+/**
+ * Used to access the theme context.
+ */
+export declare function useThemeContext(): ThemeContextValue<DefaultThemes>;

package/dist/context/theme.d.ts

@@ -0,0 +1,53 @@
+import { PropsWithChildren } from 'react';
+import { UseThemeOptions } from '../hooks/useTheme';
+/**
+ * This module provides a context and hook for the theme.
+ * @module Theme
+ */
+export type DefaultThemes = 'cerberus' | 'acheron' | 'elysium';
+export type CustomThemes<K extends string = DefaultThemes> = 'cerberus' | K;
+export type ColorModes = 'light' | 'dark' | 'system';
+export interface ThemeContextValue<T extends string = DefaultThemes> {
+    /**
+     * The current theme.
+     */
+    theme: CustomThemes<T>;
+    /**
+     * The current color mode.
+     */
+    mode: ColorModes;
+    /**
+     * Called when the theme is updated.
+     */
+    updateTheme: (theme: T) => void;
+    /**
+     * Called when the color mode is updated.
+     */
+    updateMode: (mode: ColorModes) => void;
+}
+export interface ThemeProviderProps extends UseThemeOptions {
+    /**
+     * The default theme.
+     */
+    defaultTheme?: DefaultThemes;
+    /**
+     * The default color mode.
+     */
+    defaultColorMode?: ColorModes;
+}
+/**
+ * A context provider that allows the user to set the theme and mode of the
+ * application.
+ * @see https://cerberus.digitalu.design/react/use-theme-context
+ * @example
+ * ```tsx
+ * <ThemeProvider>
+ *  <App />
+ * </ThemeProvider>
+ * ```
+ */
+export declare function ThemeProvider(props: PropsWithChildren<ThemeProviderProps>): import("react").JSX.Element;
+/**
+ * Used to access the theme context.
+ */
+export declare function useThemeContext(): ThemeContextValue<DefaultThemes>;

package/dist/context/theme.js

@@ -0,0 +1,39 @@
+"use client";
+"use client";
+import { useTheme } from "../hooks/useTheme.js";
+import { createContext, useContext } from "react";
+import { jsx } from "react/jsx-runtime";
+//#region src/context/theme.tsx
+var ThemeContext = createContext(null);
+/**
+* A context provider that allows the user to set the theme and mode of the
+* application.
+* @see https://cerberus.digitalu.design/react/use-theme-context
+* @example
+* ```tsx
+* <ThemeProvider>
+*  <App />
+* </ThemeProvider>
+* ```
+*/
+function ThemeProvider(props) {
+	const state = useTheme(props.defaultTheme, props.defaultColorMode, {
+		cache: props.cache,
+		updateMode: props.updateMode,
+		updateTheme: props.updateTheme
+	});
+	return /* @__PURE__ */ jsx(ThemeContext.Provider, {
+		value: state,
+		children: props.children
+	});
+}
+/**
+* Used to access the theme context.
+*/
+function useThemeContext() {
+	const context = useContext(ThemeContext);
+	if (!context) throw new Error("useThemeContext must be used within a ThemeProvider");
+	return context;
+}
+//#endregion
+export { ThemeProvider, useThemeContext };

package/dist/hooks/useModal.d.cts

@@ -0,0 +1,36 @@
+import { RefObject } from 'react';
+/**
+ * This module provides a hook for using a custom modal.
+ * @module
+ */
+export interface UseModalReturnValue {
+    /**
+     * The ref for the modal.
+     */
+    modalRef: RefObject<HTMLDialogElement | null>;
+    /**
+     * Shows the modal.
+     */
+    show: () => void;
+    /**
+     * Closes the modal.
+     */
+    close: () => void;
+    /**
+     * Whether the modal is open based on the show and close methods.
+     */
+    isOpen: boolean;
+}
+/**
+ * Provides a hook for using a custom modal via the native dialog element
+ * methods.
+ *
+ * Cerberus modals use the native dialog element. This hook
+ * does not control the modal via React state but rather by calling the
+ * native dialog element's `showModal` and `close` methods.
+ *
+ * @memberof module:Modal
+ * @see https://cerberus.digitalu.design/react/modal
+ * @description [Moz Dev Dialog Docs](https://developer.mozilla.org/en-US/docs/Web/API/HTMLDialogElement/showModal)
+ */
+export declare function useModal(): UseModalReturnValue;

package/dist/hooks/useModal.d.ts

@@ -0,0 +1,36 @@
+import { RefObject } from 'react';
+/**
+ * This module provides a hook for using a custom modal.
+ * @module
+ */
+export interface UseModalReturnValue {
+    /**
+     * The ref for the modal.
+     */
+    modalRef: RefObject<HTMLDialogElement | null>;
+    /**
+     * Shows the modal.
+     */
+    show: () => void;
+    /**
+     * Closes the modal.
+     */
+    close: () => void;
+    /**
+     * Whether the modal is open based on the show and close methods.
+     */
+    isOpen: boolean;
+}
+/**
+ * Provides a hook for using a custom modal via the native dialog element
+ * methods.
+ *
+ * Cerberus modals use the native dialog element. This hook
+ * does not control the modal via React state but rather by calling the
+ * native dialog element's `showModal` and `close` methods.
+ *
+ * @memberof module:Modal
+ * @see https://cerberus.digitalu.design/react/modal
+ * @description [Moz Dev Dialog Docs](https://developer.mozilla.org/en-US/docs/Web/API/HTMLDialogElement/showModal)
+ */
+export declare function useModal(): UseModalReturnValue;

package/dist/hooks/useRootColors.cjs

@@ -0,0 +1,44 @@
+"use client";
+"use client";
+let react = require("react");
+//#region src/hooks/useRootColors.ts
+/**
+* This hook returns a record of Cerberus colors from the document root.
+* This is useful when you are working with a component that uses the `<canvas>`
+* element.
+* @param colors - An array of Cerberus tokens to get from the document root (i.e. `['dataViz.diverging.50', 'dataViz.diverging.200']`).
+* @returns A record of Cerberus colors where the key is the token name provided and the value is the color hex.
+*/
+function useRootColors(colors = []) {
+	const [state, dispatch] = (0, react.useReducer)(rootColorsReducer, {});
+	const handleRefetch = (0, react.useCallback)(() => {
+		return new Promise((resolve) => {
+			dispatch(formatColors(colors));
+			resolve();
+		});
+	}, [colors]);
+	(0, react.useEffect)(() => {
+		if (Object.keys(state).length === colors.length) return;
+		dispatch(formatColors(colors));
+	}, [colors, state]);
+	return (0, react.useMemo)(() => ({
+		colors: state,
+		refetch: handleRefetch
+	}), [state, handleRefetch]);
+}
+function formatColors(colors) {
+	const rootStyles = getComputedStyle(document.body);
+	return colors.reduce((acc, color) => {
+		const formattedColor = color.replace(/([a-z])([A-Z])/g, "$1-$2").toLowerCase().replaceAll(".", "-");
+		acc[color] = rootStyles.getPropertyValue(`--cerberus-colors-${formattedColor}`).trim();
+		return acc;
+	}, {});
+}
+function rootColorsReducer(state, action) {
+	return {
+		...state,
+		...action
+	};
+}
+//#endregion
+exports.useRootColors = useRootColors;

package/dist/hooks/useRootColors.d.cts

@@ -0,0 +1,22 @@
+/**
+ * This module provides a hook to get Cerberus colors from the document root.
+ * @module useRootColors
+ */
+export interface RootColorsResult {
+    /**
+     * A record of Cerberus colors where the key is the token name provided and the value is the color hex.
+     */
+    colors: Record<string, string>;
+    /**
+     * A function to refetch the Cerberus colors from the document root. Useful when you need the latest colors after a theme/mode change.
+     */
+    refetch: () => Promise<void>;
+}
+/**
+ * This hook returns a record of Cerberus colors from the document root.
+ * This is useful when you are working with a component that uses the `<canvas>`
+ * element.
+ * @param colors - An array of Cerberus tokens to get from the document root (i.e. `['dataViz.diverging.50', 'dataViz.diverging.200']`).
+ * @returns A record of Cerberus colors where the key is the token name provided and the value is the color hex.
+ */
+export declare function useRootColors(colors?: string[]): RootColorsResult;

package/dist/hooks/useRootColors.d.ts

@@ -0,0 +1,22 @@
+/**
+ * This module provides a hook to get Cerberus colors from the document root.
+ * @module useRootColors
+ */
+export interface RootColorsResult {
+    /**
+     * A record of Cerberus colors where the key is the token name provided and the value is the color hex.
+     */
+    colors: Record<string, string>;
+    /**
+     * A function to refetch the Cerberus colors from the document root. Useful when you need the latest colors after a theme/mode change.
+     */
+    refetch: () => Promise<void>;
+}
+/**
+ * This hook returns a record of Cerberus colors from the document root.
+ * This is useful when you are working with a component that uses the `<canvas>`
+ * element.
+ * @param colors - An array of Cerberus tokens to get from the document root (i.e. `['dataViz.diverging.50', 'dataViz.diverging.200']`).
+ * @returns A record of Cerberus colors where the key is the token name provided and the value is the color hex.
+ */
+export declare function useRootColors(colors?: string[]): RootColorsResult;

package/dist/hooks/useRootColors.js

@@ -0,0 +1,44 @@
+"use client";
+"use client";
+import { useCallback, useEffect, useMemo, useReducer } from "react";
+//#region src/hooks/useRootColors.ts
+/**
+* This hook returns a record of Cerberus colors from the document root.
+* This is useful when you are working with a component that uses the `<canvas>`
+* element.
+* @param colors - An array of Cerberus tokens to get from the document root (i.e. `['dataViz.diverging.50', 'dataViz.diverging.200']`).
+* @returns A record of Cerberus colors where the key is the token name provided and the value is the color hex.
+*/
+function useRootColors(colors = []) {
+	const [state, dispatch] = useReducer(rootColorsReducer, {});
+	const handleRefetch = useCallback(() => {
+		return new Promise((resolve) => {
+			dispatch(formatColors(colors));
+			resolve();
+		});
+	}, [colors]);
+	useEffect(() => {
+		if (Object.keys(state).length === colors.length) return;
+		dispatch(formatColors(colors));
+	}, [colors, state]);
+	return useMemo(() => ({
+		colors: state,
+		refetch: handleRefetch
+	}), [state, handleRefetch]);
+}
+function formatColors(colors) {
+	const rootStyles = getComputedStyle(document.body);
+	return colors.reduce((acc, color) => {
+		const formattedColor = color.replace(/([a-z])([A-Z])/g, "$1-$2").toLowerCase().replaceAll(".", "-");
+		acc[color] = rootStyles.getPropertyValue(`--cerberus-colors-${formattedColor}`).trim();
+		return acc;
+	}, {});
+}
+function rootColorsReducer(state, action) {
+	return {
+		...state,
+		...action
+	};
+}
+//#endregion
+export { useRootColors };

package/dist/hooks/useTheme.cjs

@@ -0,0 +1,64 @@
+"use client";
+"use client";
+let react = require("react");
+//#region src/hooks/useTheme.ts
+/**
+* This module provides a hook for using the theme.
+* @module
+*/
+var THEME_KEY = "cerberus-theme";
+var MODE_KEY = "cerberus-mode";
+/**
+* Provides a hook for using the theme for a single instance of the application.
+* @see https://cerberus.digitalu.design/react/use-theme
+* @param defaultTheme The default theme.
+* @param defaultColorMode The default color mode.
+* @param options Additional options.
+*/
+function useTheme(defaultTheme = "cerberus", defaultColorMode = "light", options = {}) {
+	const { updateMode, updateTheme, cache } = options;
+	const [theme, setTheme] = (0, react.useState)(defaultTheme);
+	const [colorMode, setColorMode] = (0, react.useState)(defaultColorMode);
+	const handleThemeChange = (0, react.useCallback)((newTheme) => {
+		setTheme(newTheme);
+		updateTheme?.(newTheme);
+	}, [updateTheme]);
+	const handleColorModeChange = (0, react.useCallback)((newMode) => {
+		setColorMode(newMode);
+		updateMode?.(newMode);
+	}, [updateMode]);
+	(0, react.useLayoutEffect)(() => {
+		const theme = localStorage.getItem(THEME_KEY);
+		if (theme) setTheme(theme);
+	}, []);
+	(0, react.useLayoutEffect)(() => {
+		const mode = localStorage.getItem(MODE_KEY);
+		if (mode) setColorMode(mode);
+	}, []);
+	(0, react.useEffect)(() => {
+		const root = document.documentElement;
+		root.dataset.pandaTheme = theme;
+		if (cache) localStorage.setItem(THEME_KEY, theme);
+	}, [theme, cache]);
+	(0, react.useEffect)(() => {
+		const root = document.documentElement;
+		if (colorMode === "system") root.dataset.colorMode = window.matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light";
+		else root.dataset.colorMode = colorMode;
+		if (cache) localStorage.setItem(MODE_KEY, colorMode);
+	}, [colorMode, cache]);
+	return (0, react.useMemo)(() => ({
+		theme,
+		mode: colorMode,
+		updateTheme: handleThemeChange,
+		updateMode: handleColorModeChange
+	}), [
+		theme,
+		colorMode,
+		handleThemeChange,
+		handleColorModeChange
+	]);
+}
+//#endregion
+exports.MODE_KEY = MODE_KEY;
+exports.THEME_KEY = THEME_KEY;
+exports.useTheme = useTheme;

package/dist/hooks/useTheme.d.cts

@@ -0,0 +1,29 @@
+import { ColorModes, CustomThemes, DefaultThemes, ThemeContextValue } from '../context/theme';
+/**
+ * This module provides a hook for using the theme.
+ * @module
+ */
+export declare const THEME_KEY = "cerberus-theme";
+export declare const MODE_KEY = "cerberus-mode";
+export interface UseThemeOptions<T extends string = DefaultThemes> {
+    /**
+     * Whether to cache the theme in local storage.
+     */
+    cache?: boolean;
+    /**
+     * Called when the theme is updated.
+     */
+    updateTheme?: (theme: T) => void;
+    /**
+     * Called when the color mode is updated.
+     */
+    updateMode?: (mode: ColorModes) => void;
+}
+/**
+ * Provides a hook for using the theme for a single instance of the application.
+ * @see https://cerberus.digitalu.design/react/use-theme
+ * @param defaultTheme The default theme.
+ * @param defaultColorMode The default color mode.
+ * @param options Additional options.
+ */
+export declare function useTheme<C extends string = DefaultThemes>(defaultTheme?: CustomThemes<C>, defaultColorMode?: ColorModes, options?: UseThemeOptions<C>): ThemeContextValue<C>;

package/dist/hooks/useTheme.d.ts

@@ -0,0 +1,29 @@
+import { ColorModes, CustomThemes, DefaultThemes, ThemeContextValue } from '../context/theme';
+/**
+ * This module provides a hook for using the theme.
+ * @module
+ */
+export declare const THEME_KEY = "cerberus-theme";
+export declare const MODE_KEY = "cerberus-mode";
+export interface UseThemeOptions<T extends string = DefaultThemes> {
+    /**
+     * Whether to cache the theme in local storage.
+     */
+    cache?: boolean;
+    /**
+     * Called when the theme is updated.
+     */
+    updateTheme?: (theme: T) => void;
+    /**
+     * Called when the color mode is updated.
+     */
+    updateMode?: (mode: ColorModes) => void;
+}
+/**
+ * Provides a hook for using the theme for a single instance of the application.
+ * @see https://cerberus.digitalu.design/react/use-theme
+ * @param defaultTheme The default theme.
+ * @param defaultColorMode The default color mode.
+ * @param options Additional options.
+ */
+export declare function useTheme<C extends string = DefaultThemes>(defaultTheme?: CustomThemes<C>, defaultColorMode?: ColorModes, options?: UseThemeOptions<C>): ThemeContextValue<C>;

package/dist/hooks/useTheme.js

@@ -0,0 +1,62 @@
+"use client";
+"use client";
+import { useCallback, useEffect, useLayoutEffect, useMemo, useState } from "react";
+//#region src/hooks/useTheme.ts
+/**
+* This module provides a hook for using the theme.
+* @module
+*/
+var THEME_KEY = "cerberus-theme";
+var MODE_KEY = "cerberus-mode";
+/**
+* Provides a hook for using the theme for a single instance of the application.
+* @see https://cerberus.digitalu.design/react/use-theme
+* @param defaultTheme The default theme.
+* @param defaultColorMode The default color mode.
+* @param options Additional options.
+*/
+function useTheme(defaultTheme = "cerberus", defaultColorMode = "light", options = {}) {
+	const { updateMode, updateTheme, cache } = options;
+	const [theme, setTheme] = useState(defaultTheme);
+	const [colorMode, setColorMode] = useState(defaultColorMode);
+	const handleThemeChange = useCallback((newTheme) => {
+		setTheme(newTheme);
+		updateTheme?.(newTheme);
+	}, [updateTheme]);
+	const handleColorModeChange = useCallback((newMode) => {
+		setColorMode(newMode);
+		updateMode?.(newMode);
+	}, [updateMode]);
+	useLayoutEffect(() => {
+		const theme = localStorage.getItem(THEME_KEY);
+		if (theme) setTheme(theme);
+	}, []);
+	useLayoutEffect(() => {
+		const mode = localStorage.getItem(MODE_KEY);
+		if (mode) setColorMode(mode);
+	}, []);
+	useEffect(() => {
+		const root = document.documentElement;
+		root.dataset.pandaTheme = theme;
+		if (cache) localStorage.setItem(THEME_KEY, theme);
+	}, [theme, cache]);
+	useEffect(() => {
+		const root = document.documentElement;
+		if (colorMode === "system") root.dataset.colorMode = window.matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light";
+		else root.dataset.colorMode = colorMode;
+		if (cache) localStorage.setItem(MODE_KEY, colorMode);
+	}, [colorMode, cache]);
+	return useMemo(() => ({
+		theme,
+		mode: colorMode,
+		updateTheme: handleThemeChange,
+		updateMode: handleColorModeChange
+	}), [
+		theme,
+		colorMode,
+		handleThemeChange,
+		handleColorModeChange
+	]);
+}
+//#endregion
+export { MODE_KEY, THEME_KEY, useTheme };