@etsoo/toolpad 1.0.0

package/build/src/nextjs/AppProvider.test.js

@@ -0,0 +1,36 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import * as React from "react";
+import { describe, test, expect, vi } from "vitest";
+import { render, screen } from "@testing-library/react";
+import { AppProvider } from "./AppProvider";
+vi.mock("next/navigation", () => {
+    const searchParams = new URLSearchParams();
+    const push = () => { };
+    const replace = () => { };
+    const router = { push, replace };
+    return {
+        usePathname: () => "/",
+        useSearchParams: () => searchParams,
+        useRouter: () => router
+    };
+});
+vi.mock("next/router", () => ({ useRouter: () => null }));
+vi.mock("next/compat/router", () => ({ useRouter: () => null }));
+function RouterTest({ children }) {
+    const [pathname, setPathname] = React.useState("/page");
+    const router = React.useMemo(() => {
+        return {
+            pathname,
+            searchParams: new URLSearchParams(),
+            navigate: (path) => setPathname(String(path))
+        };
+    }, [pathname]);
+    return _jsx(AppProvider, { router: router, children: children });
+}
+describe("Nextjs AppProvider", () => {
+    test("renders content correctly", async () => {
+        // placeholder test
+        render(_jsx(RouterTest, { children: "Hello" }));
+        expect(screen.getByText("Hello")).toBeTruthy();
+    });
+});

package/build/src/nextjs/AppProviderNextApp.d.ts

@@ -0,0 +1,5 @@
+import type { AppProviderProps } from "../AppProvider";
+/**
+ * @ignore - internal component.
+ */
+export declare function AppProviderNextApp(props: AppProviderProps): import("react/jsx-runtime").JSX.Element;

package/build/src/nextjs/AppProviderNextApp.js

@@ -0,0 +1,27 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import * as React from "react";
+import { usePathname, useSearchParams, useRouter } from "next/navigation";
+import { AppProvider } from "../AppProvider/AppProviderComponent";
+/**
+ * @ignore - internal component.
+ */
+export function AppProviderNextApp(props) {
+    const pathname = usePathname();
+    const searchParams = useSearchParams();
+    const { push, replace } = useRouter();
+    const navigate = React.useCallback((url, { history = "auto" } = {}) => {
+        if (history === "auto" || history === "push") {
+            return push(String(url));
+        }
+        if (history === "replace") {
+            return replace(String(url));
+        }
+        throw new Error(`Invalid history option: ${history}`);
+    }, [push, replace]);
+    const routerImpl = React.useMemo(() => ({
+        pathname,
+        searchParams,
+        navigate
+    }), [pathname, navigate, searchParams]);
+    return _jsx(AppProvider, { router: routerImpl, ...props });
+}

package/build/src/nextjs/AppProviderNextPages.d.ts

@@ -0,0 +1,5 @@
+import type { AppProviderProps } from "../AppProvider";
+/**
+ * @ignore - internal component.
+ */
+export declare function AppProviderNextPages(props: AppProviderProps): import("react/jsx-runtime").JSX.Element;

package/build/src/nextjs/AppProviderNextPages.js

@@ -0,0 +1,37 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import * as React from "react";
+import { useRouter } from "next/router";
+import { asArray } from "../utils/collections";
+import { AppProvider } from "../AppProvider/AppProviderComponent";
+/**
+ * @ignore - internal component.
+ */
+export function AppProviderNextPages(props) {
+    const { push, replace, asPath, query } = useRouter();
+    const search = React.useMemo(() => {
+        const params = new URLSearchParams();
+        Object.entries(query ?? {}).forEach(([key, value]) => {
+            asArray(value ?? []).forEach((v) => {
+                params.append(key, v);
+            });
+        });
+        return params.toString();
+    }, [query]);
+    // Stable search params object
+    const searchParams = React.useMemo(() => new URLSearchParams(search), [search]);
+    const navigate = React.useCallback((url, { history = "auto" } = {}) => {
+        if (history === "auto" || history === "push") {
+            return push(String(url));
+        }
+        if (history === "replace") {
+            return replace(String(url));
+        }
+        throw new Error(`Invalid history option: ${history}`);
+    }, [push, replace]);
+    const routerImpl = React.useMemo(() => ({
+        pathname: asPath,
+        searchParams,
+        navigate
+    }), [asPath, navigate, searchParams]);
+    return _jsx(AppProvider, { router: routerImpl, ...props });
+}

package/build/src/nextjs/index.d.ts

@@ -0,0 +1 @@
+export * from "./AppProvider";

package/build/src/nextjs/index.js

@@ -0,0 +1 @@
+export * from "./AppProvider";

package/build/src/persistence/codec.d.ts

@@ -0,0 +1,47 @@
+/**
+ * A codec that can encode and decode values of type V to and from strings.
+ * @typeParam V The type of values that can be encoded and decoded.
+ */
+export interface Codec<V> {
+    /**
+     * Decodes a string value into a value of type V.
+     * @param value The value to decode.
+     * @returns The decoded value.
+     */
+    parse: (value: string) => V;
+    /**
+     * Encodes a value of type V into a string.
+     * @param value The value to encode.
+     * @returns The encoded value.
+     */
+    stringify: (value: V) => string;
+}
+/**
+ * A codec that can encode and decode Date objects to and from strings.
+ */
+export declare const CODEC_DATE: Codec<Date>;
+/**
+ * A codec that can encode and decode Date objects to and from strings, but only the date part.
+ */
+export declare const CODEC_DATE_ONLY: Codec<Date>;
+/**
+ * A codec that can encode and decode numbers to and from strings.
+ */
+export declare const CODEC_NUMBER: Codec<number>;
+/**
+ * A codec that can encode and decode boolean values to and from strings.
+ */
+export declare const CODE_BOOLEAN: Codec<boolean>;
+/**
+ * A codec that can encode and decode JSON values to and from strings.
+ */
+export declare const CODEC_JSON: Codec<unknown>;
+/**
+ * A codec that can encode and decode JSON values to and from strings.
+ * If the JSON value is invalid, parsing will fail.
+ */
+export declare const CODEC_JSON_STRICT: Codec<unknown>;
+/**
+ * A codec that can encode and decode strings to and from strings.
+ */
+export declare const CODEC_STRING: Codec<string>;

package/build/src/persistence/codec.js

@@ -0,0 +1,57 @@
+/**
+ * A codec that can encode and decode Date objects to and from strings.
+ */
+export const CODEC_DATE = {
+    parse: (value) => new Date(value),
+    stringify: (value) => value.toISOString()
+};
+/**
+ * A codec that can encode and decode Date objects to and from strings, but only the date part.
+ */
+export const CODEC_DATE_ONLY = {
+    parse: (value) => new Date(value),
+    stringify: (value) => value.toISOString().split("T")[0]
+};
+/**
+ * A codec that can encode and decode numbers to and from strings.
+ */
+export const CODEC_NUMBER = {
+    parse: (value) => Number(value),
+    stringify: (value) => String(value)
+};
+/**
+ * A codec that can encode and decode boolean values to and from strings.
+ */
+export const CODE_BOOLEAN = {
+    parse: (value) => value === "true",
+    stringify: (value) => String(value)
+};
+/**
+ * A codec that can encode and decode JSON values to and from strings.
+ */
+export const CODEC_JSON = {
+    parse: (value) => {
+        try {
+            return JSON.parse(value);
+        }
+        catch {
+            return null;
+        }
+    },
+    stringify: (value) => JSON.stringify(value)
+};
+/**
+ * A codec that can encode and decode JSON values to and from strings.
+ * If the JSON value is invalid, parsing will fail.
+ */
+export const CODEC_JSON_STRICT = {
+    parse: (value) => JSON.parse(value),
+    stringify: (value) => JSON.stringify(value)
+};
+/**
+ * A codec that can encode and decode strings to and from strings.
+ */
+export const CODEC_STRING = {
+    parse: (value) => value,
+    stringify: (value) => value
+};

package/build/src/persistence/index.d.ts

@@ -0,0 +1 @@
+export * from "./useStorageState";

package/build/src/persistence/index.js

@@ -0,0 +1 @@
+export * from "./useStorageState";

package/build/src/persistence/useStorageState.d.ts

@@ -0,0 +1,50 @@
+import * as React from "react";
+import { Codec } from "./codec";
+export type StorageStateInitializer<T> = () => T | null;
+export type UseStorageStateHookResult<T> = [
+    T | null,
+    React.Dispatch<React.SetStateAction<T | null>>
+];
+export declare function useStorageStateServer<T = string>(): UseStorageStateHookResult<T>;
+export interface DefaultStorageStateoptions<T = string> {
+    codec?: Codec<T>;
+}
+export interface StorageStateOptions<T> extends DefaultStorageStateoptions<T> {
+    codec: Codec<T>;
+}
+/**
+ * Sync state to local storage so that it persists through a page refresh. Usage is
+ * similar to useState except we pass in a storage key so that we can default
+ * to that value on page load instead of the specified initial value.
+ *
+ * Since the storage API isn't available in server-rendering environments, we
+ * return null during SSR and hydration.
+ */
+export declare function useStorageState(area: Storage, key: string | null, initializer?: string | null | StorageStateInitializer<string>, options?: DefaultStorageStateoptions): UseStorageStateHookResult<string>;
+export declare function useStorageState<T>(area: Storage, key: string | null, initializer: T | null | StorageStateInitializer<T>, options: StorageStateOptions<T>): UseStorageStateHookResult<T>;
+export interface UseStorageState {
+    /**
+     * Sync state to local or session storage so that it persists through a page refresh. Usage is
+     * similar to useState except we pass in a storage key that uniquely identifies the value.
+     * @param key The key to use for storing the value in local or session storage.
+     * @param initializer The initial value to use if the key is not present in storage.
+     * @param options Additional options for the storage state.
+     */
+    (key: string | null, initializer?: string | null | StorageStateInitializer<string>, options?: DefaultStorageStateoptions): UseStorageStateHookResult<string>;
+    /**
+     * Sync state to local or session storage so that it persists through a page refresh. Usage is
+     * similar to useState except we pass in a storage key that uniquely identifies the value.
+     * @param key The key to use for storing the value in local or session storage.
+     * @param initializer The initial value to use if the key is not present in storage.
+     * @param options Additional options for the storage state.
+     */
+    <T>(key: string | null, initializer: T | null | StorageStateInitializer<T>, options: StorageStateOptions<T>): UseStorageStateHookResult<T>;
+    /**
+     * Sync state to local or session storage so that it persists through a page refresh. Usage is
+     * similar to useState except we pass in a storage key that uniquely identifies the value.
+     * @param key The key to use for storing the value in local or session storage.
+     * @param initializer The initial value to use if the key is not present in storage.
+     * @param options Additional options for the storage state.
+     */
+    <T>(key: string | null, initializer?: T | null | StorageStateInitializer<T>, options?: StorageStateOptions<T>): UseStorageStateHookResult<T>;
+}

package/build/src/persistence/useStorageState.js

@@ -0,0 +1,116 @@
+"use client";
+import * as React from "react";
+import { CODEC_STRING } from "./codec";
+// storage events only work across tabs, we'll use an event emitter to announce within the current tab
+const currentTabChangeListeners = new Map();
+function onCurrentTabStorageChange(key, handler) {
+    let listeners = currentTabChangeListeners.get(key);
+    if (!listeners) {
+        listeners = new Set();
+        currentTabChangeListeners.set(key, listeners);
+    }
+    listeners.add(handler);
+}
+function offCurrentTabStorageChange(key, handler) {
+    const listeners = currentTabChangeListeners.get(key);
+    if (!listeners) {
+        return;
+    }
+    listeners.delete(handler);
+    if (listeners.size === 0) {
+        currentTabChangeListeners.delete(key);
+    }
+}
+function emitCurrentTabStorageChange(key) {
+    const listeners = currentTabChangeListeners.get(key);
+    if (listeners) {
+        listeners.forEach((listener) => listener());
+    }
+}
+if (typeof window !== "undefined") {
+    const origSetItem = window.localStorage.setItem;
+    window.localStorage.setItem = function setItem(key, value) {
+        const result = origSetItem.call(this, key, value);
+        emitCurrentTabStorageChange(key);
+        return result;
+    };
+}
+function subscribe(area, key, callback) {
+    if (!key) {
+        return () => { };
+    }
+    const storageHandler = (event) => {
+        if (event.storageArea === area && event.key === key) {
+            callback();
+        }
+    };
+    window.addEventListener("storage", storageHandler);
+    onCurrentTabStorageChange(key, callback);
+    return () => {
+        window.removeEventListener("storage", storageHandler);
+        offCurrentTabStorageChange(key, callback);
+    };
+}
+function getSnapshot(area, key) {
+    if (!key) {
+        return null;
+    }
+    try {
+        return area.getItem(key);
+    }
+    catch {
+        // ignore
+        // See https://developer.mozilla.org/en-US/docs/Web/API/Web_Storage_API/Using_the_Web_Storage_API#feature-detecting_localstorage
+        return null;
+    }
+}
+function setValue(area, key, value) {
+    if (!key) {
+        return;
+    }
+    try {
+        if (value === null) {
+            area.removeItem(key);
+        }
+        else {
+            area.setItem(key, String(value));
+        }
+    }
+    catch {
+        // ignore
+        // See https://developer.mozilla.org/en-US/docs/Web/API/Web_Storage_API/Using_the_Web_Storage_API#feature-detecting_localstorage
+        return;
+    }
+    emitCurrentTabStorageChange(key);
+}
+const serverValue = [null, () => { }];
+export function useStorageStateServer() {
+    return serverValue;
+}
+function encode(codec, value) {
+    return value === null ? null : codec.stringify(value);
+}
+function decode(codec, value) {
+    return value === null ? null : codec.parse(value);
+}
+// Start with null for the hydration, and then switch to the actual value.
+const getKeyServerSnapshot = () => null;
+export function useStorageState(area, key, initializer = null, options) {
+    const codec = (options?.codec ?? CODEC_STRING);
+    const [initialValue] = React.useState(initializer);
+    const encodedInitialValue = React.useMemo(() => encode(codec, initialValue), [codec, initialValue]);
+    const subscribeKey = React.useCallback((callback) => subscribe(area, key, callback), [area, key]);
+    const getKeySnapshot = React.useCallback(() => getSnapshot(area, key) ?? encodedInitialValue, [area, encodedInitialValue, key]);
+    const encodedStoredValue = React.useSyncExternalStore(subscribeKey, getKeySnapshot, getKeyServerSnapshot);
+    const storedValue = React.useMemo(() => decode(codec, encodedStoredValue), [codec, encodedStoredValue]);
+    const setStoredValue = React.useCallback((value) => {
+        const valueToStore = value instanceof Function ? value(storedValue) : value;
+        const encodedValueToStore = encode(codec, valueToStore);
+        setValue(area, key, encodedValueToStore);
+    }, [area, codec, storedValue, key]);
+    const [nonStoredValue, setNonStoredValue] = React.useState(initialValue);
+    if (!key) {
+        return [nonStoredValue, setNonStoredValue];
+    }
+    return [storedValue, setStoredValue];
+}

package/build/src/persistence/useStorageState.test.d.ts

@@ -0,0 +1 @@
+export {};

package/build/src/persistence/useStorageState.test.js

@@ -0,0 +1,61 @@
+import { describe, test, expect, beforeEach } from "vitest";
+import { act, renderHook } from "@testing-library/react";
+import { useStorageState } from "./useStorageState";
+describe("useStorageState", () => {
+    beforeEach(() => {
+        window.localStorage.clear();
+    });
+    test("can do basic local storage with initial value", async () => {
+        const { result, rerender } = renderHook(() => useStorageState(window.localStorage, "foo", "bar"));
+        expect(result.current[0]).toBe("bar");
+        act(() => {
+            result.current[1]("baz");
+        });
+        rerender();
+        expect(result.current[0]).toBe("baz");
+    });
+    test("can do basic local storage without initial value", async () => {
+        const { result, rerender } = renderHook(() => useStorageState(window.localStorage, "foo"));
+        expect(result.current[0]).toBe(null);
+        act(() => {
+            result.current[1]("baz");
+        });
+        rerender();
+        expect(result.current[0]).toBe("baz");
+    });
+    test("can clear storage value, and reset to intiial value", async () => {
+        const { result, rerender } = renderHook(() => useStorageState(window.localStorage, "foo", "bar"));
+        act(() => {
+            result.current[1]("baz");
+        });
+        rerender();
+        expect(result.current[0]).toBe("baz");
+        act(() => {
+            result.current[1](null);
+        });
+        rerender();
+        expect(result.current[0]).toBe("bar");
+    });
+    test("can clear storage value", async () => {
+        const { result, rerender } = renderHook(() => useStorageState(window.localStorage, "foo"));
+        act(() => {
+            result.current[1]("baz");
+        });
+        rerender();
+        expect(result.current[0]).toBe("baz");
+        act(() => {
+            result.current[1](null);
+        });
+        rerender();
+        expect(result.current[0]).toBe(null);
+    });
+    test("can handle complex types", async () => {
+        const { result, rerender } = renderHook(() => useStorageState(window.localStorage, "foo", { a: 1 }, { codec: JSON }));
+        expect(result.current[0]).toEqual({ a: 1 });
+        act(() => {
+            result.current[1]({ b: 2 });
+        });
+        rerender();
+        expect(result.current[0]).toEqual({ b: 2 });
+    });
+});

package/build/src/react-router-dom/AppProvider.d.ts

@@ -0,0 +1,6 @@
+import { type AppProviderProps } from "../AppProvider";
+/**
+ * @ignore - internal component.
+ */
+declare function AppProvider(props: AppProviderProps): import("react/jsx-runtime").JSX.Element;
+export { AppProvider };

package/build/src/react-router-dom/AppProvider.js

@@ -0,0 +1,29 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import * as React from "react";
+import { useSearchParams, useLocation, useNavigate } from "react-router-dom";
+import { AppProvider as AppProviderComponent } from "../AppProvider/AppProviderComponent";
+/**
+ * @ignore - internal component.
+ */
+function AppProvider(props) {
+    const { pathname } = useLocation();
+    const [searchParams] = useSearchParams();
+    const navigate = useNavigate();
+    const navigateImpl = React.useCallback((url, { history = "auto" } = {}) => {
+        if (history === "auto" || history === "push") {
+            return navigate(url);
+        }
+        if (history === "replace") {
+            return navigate(url, { replace: true });
+        }
+        throw new Error(`Invalid history option: ${history}`);
+    }, [navigate]);
+    const routerImpl = React.useMemo(() => ({
+        pathname,
+        searchParams,
+        navigate: navigateImpl
+    }), [pathname, searchParams, navigateImpl]);
+    return _jsx(AppProviderComponent, { router: routerImpl, ...props });
+}
+export { AppProvider };

package/build/src/react-router-dom/AppProvider.test.d.ts

@@ -0,0 +1 @@
+export {};

package/build/src/react-router-dom/AppProvider.test.js

@@ -0,0 +1,12 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { describe, test, expect } from "vitest";
+import { render, screen } from "@testing-library/react";
+import { BrowserRouter } from "react-router-dom";
+import { AppProvider } from "./AppProvider";
+describe("React Router AppProvider", () => {
+    test("renders content correctly", async () => {
+        // placeholder test
+        render(_jsx(BrowserRouter, { children: _jsx(AppProvider, { children: "Hello" }) }));
+        expect(screen.getByText("Hello")).toBeTruthy();
+    });
+});

package/build/src/react-router-dom/index.d.ts

@@ -0,0 +1 @@
+export * from "./AppProvider";

package/build/src/react-router-dom/index.js

@@ -0,0 +1 @@
+export * from "./AppProvider";

package/build/src/shared/Link.d.ts

@@ -0,0 +1,8 @@
+import * as React from "react";
+/**
+ * @ignore - internal component.
+ */
+export interface LinkProps extends React.AnchorHTMLAttributes<HTMLAnchorElement> {
+    history?: "auto" | "push" | "replace";
+}
+export declare const Link: React.ForwardRefExoticComponent<LinkProps & React.RefAttributes<HTMLAnchorElement>>;

package/build/src/shared/Link.js

@@ -0,0 +1,19 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import * as React from "react";
+import { RouterContext } from "./context";
+export const Link = React.forwardRef(function Link(props, ref) {
+    const { children, href, onClick, history, ...rest } = props;
+    const routerContext = React.useContext(RouterContext);
+    const handleLinkClick = React.useMemo(() => {
+        if (!routerContext) {
+            return onClick;
+        }
+        return (event) => {
+            event.preventDefault();
+            const url = new URL(event.currentTarget.href);
+            routerContext.navigate(url.pathname, { history });
+            onClick?.(event);
+        };
+    }, [routerContext, onClick, history]);
+    return (_jsx("a", { ref: ref, href: href, ...rest, onClick: handleLinkClick, children: children }));
+});

package/build/src/shared/branding.d.ts

@@ -0,0 +1 @@
+export declare function useApplicationTitle(): string;

package/build/src/shared/branding.js

@@ -0,0 +1,6 @@
+import * as React from "react";
+import { BrandingContext } from "./context";
+export function useApplicationTitle() {
+    const branding = React.useContext(BrandingContext);
+    return branding?.title ?? "Toolpad";
+}

package/build/src/shared/components.d.ts

@@ -0,0 +1,5 @@
+export interface ErrorOverlayProps {
+    error?: unknown;
+}
+export declare function ErrorOverlay({ error }: ErrorOverlayProps): import("react/jsx-runtime").JSX.Element;
+export declare function LoadingOverlay(): import("react/jsx-runtime").JSX.Element;

package/build/src/shared/components.js

@@ -0,0 +1,23 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { CircularProgress, Typography, styled } from "@mui/material";
+import ErrorIcon from "@mui/icons-material/Error";
+const OverlayRoot = styled("div")(({ theme }) => ({
+    position: "absolute",
+    inset: "0 0 0 0",
+    display: "flex",
+    flexDirection: "column",
+    alignItems: "center",
+    justifyContent: "center",
+    padding: theme.spacing(2)
+}));
+export function ErrorOverlay({ error }) {
+    return (_jsxs(OverlayRoot, { children: [_jsxs(Typography, { variant: "h6", sx: {
+                    display: "flex",
+                    flexDirection: "row",
+                    gap: 1,
+                    alignItems: "center"
+                }, children: [_jsx(ErrorIcon, { color: "error" }), " Error"] }), _jsx(Typography, { textAlign: "center", children: error?.message ?? "Unknown error" })] }));
+}
+export function LoadingOverlay() {
+    return (_jsx(OverlayRoot, { children: _jsx(CircularProgress, {}) }));
+}

package/build/src/shared/context.d.ts

@@ -0,0 +1,12 @@
+import * as React from "react";
+import type { PaletteMode } from "@mui/material";
+import type { Branding, Navigation, Router } from "../AppProvider";
+export declare const BrandingContext: React.Context<Branding | null>;
+export declare const NavigationContext: React.Context<Navigation>;
+export declare const PaletteModeContext: React.Context<{
+    paletteMode: PaletteMode;
+    setPaletteMode: (mode: PaletteMode) => void;
+    isDualTheme: boolean;
+}>;
+export declare const RouterContext: React.Context<Router | null>;
+export declare const WindowContext: React.Context<Window | undefined>;

package/build/src/shared/context.js

@@ -0,0 +1,10 @@
+import * as React from "react";
+export const BrandingContext = React.createContext(null);
+export const NavigationContext = React.createContext([]);
+export const PaletteModeContext = React.createContext({
+    paletteMode: "light",
+    setPaletteMode: () => { },
+    isDualTheme: false
+});
+export const RouterContext = React.createContext(null);
+export const WindowContext = React.createContext(undefined);

package/build/src/shared/locales/LocaleContext.d.ts

@@ -0,0 +1,19 @@
+import * as React from "react";
+export type LocaleContextType = {
+    signInLabel?: string;
+    signOutLabel?: string;
+    iconButtonAriaLabel?: string;
+};
+export declare const LocaleContext: React.Context<LocaleContextType>;
+export interface LocaleProviderProps {
+    localeText?: Partial<LocaleContextType>;
+    children: React.ReactNode;
+}
+/**
+ * @ignore - internal component.
+ */
+export declare function LocaleProvider({ localeText, children }: LocaleProviderProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * @ignore - internal hook.
+ */
+export declare function useLocaleText(): LocaleContextType;